pasika 0.1.0 → 0.1.4

package/docs/code-organization-guide/rules/types-and-schemas-rule.md

@@ -0,0 +1,138 @@
+# Types and Schemas Rule
+
+Types and schemas are easy to bury in component files or scatter across the project. This rule keeps them close to one component and gives independently used ones a consistent location.
+
+- A type or schema used only to implement one configuration object MUST live in that object's `types/` or `schemas/` folder.
+- Except for a type or schema used only to implement one configuration object, a type or schema declared in a component MUST stay in that component file until another file imports it without the component where it is defined. Importing it alongside that component does not trigger extraction.
+- Except for a type or schema used only to implement one configuration object, a type or schema declared outside a component MUST stay with its declaring module until another file imports it independently.
+- Extracted types and schemas MUST live in their matching `types/` or `schemas/` folder at the closest common folder (CCF) of their consumers.
+- A `types/` or `schemas/` `index.ts` MAY define its exports directly.
+- Types and schemas that are used together MAY be grouped in a file with a kebab-case name and named-re-exported from `index.ts`.
+- When a `types/` or `schemas/` folder uses grouped files, its `index.ts` MUST only named-re-export those files.
+- When a type or schema's CCF is `src/features/`, it MUST move to `src/types/` or `src/schemas/`.
+
+## Incorrect — Feature and Composition Type Kept in a Feature
+
+```text
+src/
+├── compositions/
+│   └── BillingDashboard.tsx
+├── features/
+│   └── billing/
+│       ├── invoice.tsx
+│       └── types/
+│           ├── billing.ts
+│           └── index.ts
+```
+
+```tsx
+// src/features/billing/invoice.tsx
+import type { InvoiceStatus } from "./types";
+
+// src/compositions/BillingDashboard.tsx
+import type { InvoiceStatus } from "@/features/billing/types";
+```
+
+Why: the feature and composition have `src/` as their CCF, but the type remains in the billing feature.
+
+## Correct — Feature and Composition Type in `src/types/`
+
+```text
+src/
+├── compositions/
+│   └── BillingDashboard.tsx
+├── features/
+│   └── billing/
+│       └── invoice.tsx
+└── types/
+    ├── billing.ts
+    └── index.ts
+```
+
+```ts
+// src/types/billing.ts
+export type InvoiceStatus = "draft" | "paid";
+export type PaymentMethod = "card" | "bank";
+
+// src/types/index.ts
+export type { InvoiceStatus, PaymentMethod } from "./billing";
+```
+
+```tsx
+// src/features/billing/invoice.tsx
+import type { InvoiceStatus } from "@/types";
+
+// src/compositions/BillingDashboard.tsx
+import type { InvoiceStatus } from "@/types";
+```
+
+Why: the feature and composition have `src/` as their CCF, so the type lives in `src/types/`.
+
+## Incorrect — Type Imported Independently from a Component
+
+```tsx
+// src/features/billing/invoice.tsx
+export type DateRange = { from: Date; to: Date };
+
+export function Invoice({ range }: { range: DateRange }): React.JSX.Element {
+  return <InvoiceView range={range} />;
+}
+```
+
+```ts
+// src/features/billing/hooks/use-billing-filter.ts
+import type { DateRange } from "../invoice";
+```
+
+Why: the hook reaches into a component file for a type it uses independently.
+
+## Correct — Independently Used Type Extracted
+
+```ts
+// src/features/billing/types/index.ts
+export type DateRange = { from: Date; to: Date };
+
+// src/features/billing/hooks/use-billing-filter.ts
+import { type DateRange } from "../types";
+```
+
+Why: the component and hook can use the billing feature's types index independently.
+
+## Incorrect — Schema Imported Independently from a Component
+
+```tsx
+// src/features/billing/invoice-form.tsx
+import { z } from "zod";
+
+export const invoiceSchema = z.object({
+  amount: z.number().positive(),
+});
+```
+
+```ts
+// src/features/billing/hooks/use-invoice-draft.ts
+import { invoiceSchema } from "../invoice-form";
+```
+
+Why: the hook reaches into a component file for a schema it uses independently.
+
+## Correct — Independently Used Schema Extracted
+
+```ts
+// src/features/billing/schemas/index.ts
+import { z } from "zod";
+
+export const invoiceSchema = z.object({
+  amount: z.number().positive(),
+});
+```
+
+```tsx
+// src/features/billing/invoice-form.tsx
+import { invoiceSchema } from "./schemas";
+
+// src/features/billing/hooks/use-invoice-draft.ts
+import { invoiceSchema } from "../schemas";
+```
+
+Why: the component and hook can use the billing feature's schemas index independently.

package/docs/code-organization-guide/rules/utilities-rule.md

@@ -0,0 +1,87 @@
+# Utilities Rule
+
+Pure functions should not be hidden in component files. This rule extracts them to a predictable `utils/` folder and keeps their imports direct.
+
+- A pure function MUST be extracted to `utils/`, even when it has one consumer.
+- A pure function returns the same result for the same arguments and does not read or write external mutable state, perform I/O, or manipulate the DOM.
+- A utility used only to implement one configuration object MUST live in that object's `utils/` folder.
+- An extracted utility MUST live in the `utils/` folder at the closest common folder (CCF) of its consumers.
+- When a utility's CCF is `src/features/`, it MUST move to `src/utils/`.
+- A utility MUST be imported directly without a barrel.
+- A utility file that exports one function MUST have a name in that function's kebab-case form.
+- Utilities that are used together MAY be grouped in a file with a kebab-case name.
+
+## Incorrect — Pure Function Left Beside Its Consumer
+
+```tsx
+// src/features/billing/invoice.tsx
+const calculateInvoiceTotal = (items: InvoiceItem[]): number => {
+  return items.reduce((total, item) => total + item.amount, 0);
+};
+
+export function Invoice({ items }: InvoiceProps): React.JSX.Element {
+  const total = calculateInvoiceTotal(items);
+  return <InvoiceTotal value={total} />;
+}
+```
+
+Why: the pure function is mixed into a component file.
+
+## Correct — Pure Function in a Directly Imported Utility File
+
+```ts
+// src/features/billing/utils/calculate-invoice-total.ts
+export function calculateInvoiceTotal(items: InvoiceItem[]): number {
+  return items.reduce((total, item) => total + item.amount, 0);
+}
+```
+
+```tsx
+// src/features/billing/invoice.tsx
+import { calculateInvoiceTotal } from "./utils/calculate-invoice-total";
+
+export function Invoice({ items }: InvoiceProps): React.JSX.Element {
+  const total = calculateInvoiceTotal(items);
+  return <InvoiceTotal value={total} />;
+}
+```
+
+Why: the function has a focused utility file in the billing feature's `utils/` folder.
+
+## Incorrect — Shared Utility Kept in a Feature
+
+```ts
+// src/features/billing/utils/format-retry-delay.ts
+export function formatRetryDelay(milliseconds: number): string {
+  return `${milliseconds / 1000} seconds`;
+}
+```
+
+```tsx
+// src/features/billing/invoice.tsx
+import { formatRetryDelay } from "./utils/format-retry-delay";
+
+// src/compositions/billing-dashboard.tsx
+import { formatRetryDelay } from "@/features/billing/utils/format-retry-delay";
+```
+
+Why: the utility is imported by both a feature and a composition, so it cannot stay in the billing feature.
+
+## Correct — Shared Utility in `src/utils/`
+
+```ts
+// src/utils/format-retry-delay.ts
+export function formatRetryDelay(milliseconds: number): string {
+  return `${milliseconds / 1000} seconds`;
+}
+```
+
+```tsx
+// src/features/billing/invoice.tsx
+import { formatRetryDelay } from "@/utils/format-retry-delay";
+
+// src/compositions/billing-dashboard.tsx
+import { formatRetryDelay } from "@/utils/format-retry-delay";
+```
+
+Why: the utility's CCF is `src/`, so it lives in `src/utils/`.

package/docs/documentation-guide/_templates/guide.md

@@ -0,0 +1,19 @@
+# [Topic] Guide
+
+[1-2 short sentences explaining the underlying idea behind this guide and why it matters.]
+
+## How To [Workflow]
+
+[What does this accomplish? When should it run?]
+
+1. [Step 1]
+2. [Step 2]
+
+## How To [Another Workflow]
+
+[What does this accomplish? When should it run?]
+
+1. [Step 1]
+2. [Step 2]
+
+[Repeat this section only when the guide has another real workflow. Otherwise delete it.]

package/docs/documentation-guide/_templates/reference.md

@@ -0,0 +1,17 @@
+# [Topic] Reference
+
+[1-2 short sentences naming exactly what readers can look up here and when they should use this reference.]
+
+[Single lookup content — table, glossary, hierarchy, catalog, or config block. Keep this branch only when the reference has exactly one lookup block; it has no section heading. Otherwise delete this branch and use one heading per lookup group below.]
+
+## [First Lookup Group Name]
+
+[1-2 short sentences explaining what this group contains and why it is included.]
+
+[Place this group's lookup content here.]
+
+## [Next Lookup Group Name]
+
+[1-2 short sentences explaining what this group contains and why it is included.]
+
+[Place this group's lookup content here. Repeat the heading, explanation, and lookup content for every remaining group; delete this multi-block branch when the reference has one lookup block.]

package/docs/documentation-guide/_templates/rule.md

@@ -0,0 +1,21 @@
+# [Rule Name] Rule
+
+[What problem does this rule solve?]
+
+- [Requirement using MUST, MUST NOT, SHOULD, SHOULD NOT, or MAY]
+
+## Incorrect — [Concise example description]
+
+```[lang]
+// code
+```
+
+Why: [What makes this incorrect?]
+
+## Correct — [Concise example description]
+
+```[lang]
+// code
+```
+
+Why: [What makes this correct?]

package/docs/documentation-guide/documentation-guide.md

@@ -0,0 +1,13 @@
+# Documentation Guide
+
+This guide explains how to create Rules, References, and Guides in this repository.
+
+## How To Create a Document
+
+Run this whenever you add a new doc to the repository.
+
+1. Pick the document kind from the [Documentation Types Reference](references/documentation-types-reference.md) so you know the right template.
+2. Follow the [Template Usage Rule](rules/template-usage-rule.md) so the doc has no leftover bracketed prompts.
+3. For a Guide, follow the [Guide Creation Rule](rules/guide-creation-rule.md) so the doc has the correct shape, naming, and folder layout.
+4. For a Rule, follow the [Rule Creation Rule](rules/rule-creation-rule.md) so the doc has the correct shape, naming, and vocabulary.
+5. For a Reference, follow the [Reference Creation Rule](rules/reference-creation-rule.md) so the doc has the correct shape, naming, and folder layout.

package/docs/documentation-guide/references/documentation-types-reference.md

@@ -0,0 +1,9 @@
+# Documentation Types Reference
+
+Use this reference to look up the three standard Markdown document kinds in this repository. Their templates are in `docs/documentation-guide/_templates/`.
+
+| Kind      | Shape                                                                                           | Template                                         |
+| --------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| Guide     | A workflow-oriented document with one or more `## How To [...]` sections.                       | `guide.md`                                      |
+| Rule      | An opinionated project rule that states required, forbidden, recommended, or optional behavior. | `rule.md`                                       |
+| Reference | Lookup material such as a table, hierarchy, configuration block, glossary, or catalog.          | `reference.md`                                  |

package/docs/documentation-guide/rules/guide-creation-rule.md

@@ -0,0 +1,112 @@
+# Guide Creation Rule
+
+Guides without a consistent creation process invent their own structure. This rule defines how to create a Guide document.
+
+- Each How To step MUST be concise and use one sentence.
+- A Guide MAY reference Rules, References, and other Guides.
+- Each How To step MUST link at most one documentation file total, whether that file is a Rule, Reference, or Guide.
+- When a step links a Rule, Reference, or Guide, the step MUST name the concrete decision or result the reader will have after reading it.
+- A step that links another Guide MUST link directly to the relevant How To section.
+- How To sections MUST NOT nest inside other How To sections.
+- Guide file names MUST match the document title in kebab-case and use the `-guide` suffix (e.g., `foo-guide.md`).
+- A Guide with private support files MUST become a folder named the same as its entry-point file, without the `.md` extension.
+- Private Rule files for a Guide MUST live in a `rules/` subfolder inside the Guide's folder.
+- Private Reference files for a Guide MUST live in a `references/` subfolder inside the Guide's folder.
+
+## Incorrect — Private Documents Mixed at the Guide Root
+
+```text
+feature-workflow-guide/
+├── feature-workflow-guide.md
+├── naming-rule.md
+└── option-reference.md
+```
+
+Why: mixed Markdown files turn the doc folder into an undifferentiated list once the doc grows.
+
+## Correct — Private Documents Grouped by Kind
+
+```text
+feature-workflow-guide/
+├── feature-workflow-guide.md
+├── rules/
+│   └── naming-rule.md
+└── references/
+    └── option-reference.md
+```
+
+Why: private support files stay colocated with the entry point while being grouped by document kind.
+
+## Incorrect — Step Links to Multiple Documents
+
+```markdown
+1. Follow the [Naming Rule](rules/naming-rule.md) and the [Layout Rule](rules/layout-rule.md) so the doc looks right.
+```
+
+Why: step links two Rules and does not name a concrete decision or result.
+
+## Correct — Step Links to One Document
+
+```markdown
+1. Follow the [Naming Rule](rules/naming-rule.md) so the doc has a predictable file name.
+```
+
+Why: step links one Rule and names the concrete result the reader will have.
+
+## Incorrect — Nested How To Section
+
+```markdown
+## How To Deploy
+
+1. Build the project.
+   ### How To Build
+   1. Run the build script.
+```
+
+Why: a How To section nests inside a step of another How To section.
+
+## Correct — Flat How To Sections
+
+```markdown
+## How To Deploy
+
+1. Follow [How To Build](#how-to-build) to build the project.
+
+## How To Build
+
+1. Run the build script.
+```
+
+Why: How To sections stay flat and reference each other via links.
+
+## Incorrect — Multi-Sentence Step
+
+```markdown
+1. First, check the configuration file. Then verify all required fields are present. After that, confirm none of the fields contain invalid values.
+```
+
+Why: step uses multiple sentences instead of one concise sentence.
+
+## Correct — Concise Step
+
+```markdown
+1. Run the config check script.
+```
+
+Why: step is one concise sentence with a concrete action.
+
+## Incorrect — Guide Link Omits Its How To Section
+
+```markdown
+1. Follow the [Build Guide](build-guide.md) to build the project.
+```
+
+Why: link points at a Guide file but does not anchor to a specific How To section, so the reader lands on the guide's introduction and has to search for the relevant workflow.
+
+## Correct — Guide Link Targets Its How To Section
+
+```markdown
+1. Follow [How To Build](build-guide.md#how-to-build) to build the project.
+```
+
+Why: link anchors to the specific How To section, so the reader lands directly on the relevant workflow.

package/docs/documentation-guide/rules/reference-creation-rule.md

@@ -0,0 +1,132 @@
+# Reference Creation Rule
+
+References without a consistent creation process scatter lookup material. This rule defines how to create a Reference document.
+
+- Reference file names MUST match the document title in kebab-case and use the `-reference` suffix (e.g., `foo-reference.md`).
+- A Reference MUST NOT link to Rules, Guides, or other References.
+- A Reference MUST NOT use RFC 2119 vocabulary (`MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, `MAY`), because lookup material describes what exists rather than imposing requirements.
+- A Reference document overview and each section overview MUST contain one or two short sentences.
+- A Reference with a single lookup block MUST NOT add a section heading for it.
+- A Reference with two or more lookup blocks MUST add a section heading for every block, including the first.
+
+## Incorrect — Reference Links to Another Document
+
+```markdown
+- See the [Naming Rule](../rules/naming-rule.md) for the file naming conventions.
+```
+
+Why: reference body contains a reference to another Rule.
+
+## Correct — Reference States the Lookup Fact Directly
+
+```markdown
+- File names are kebab-case, match the document title, and have a `-reference` suffix.
+```
+
+Why: reference states lookup content directly without linking to its source.
+
+## Incorrect — Reference Uses Requirement Vocabulary
+
+```markdown
+| Layer | Contents                                          |
+| ----- | ------------------------------------------------- |
+| `app` | Routing files only — a route MUST NOT hold a util |
+```
+
+Why: the cell carries RFC 2119 vocabulary, so a Reference asserts a requirement that only a Rule can own, and the same constraint ends up stated in two documents.
+
+## Correct — Reference Describes Existing Content
+
+```markdown
+| Layer | Contents           |
+| ----- | ------------------ |
+| `app` | Routing files only |
+```
+
+Why: the cell describes what the layer holds, leaving the requirement to the Rule that owns it.
+
+## Incorrect — Single Lookup Block Has a Heading
+
+```markdown
+# Option Reference
+
+Use this reference to choose between the two supported project sizes when starting a new initiative.
+
+## Options
+
+Pick the size that matches the team's headcount and timeline.
+
+| Option | Use Case       |
+| ------ | -------------- |
+| A      | Small projects |
+| B      | Large projects |
+```
+
+Why: section heading is unnecessary and forces a duplicated intro covering what the reference is for and what the group contains.
+
+## Correct — Single Lookup Block Has No Heading
+
+```markdown
+# Option Reference
+
+Use this reference to choose between the two supported project sizes when starting a new initiative.
+
+| Option | Use Case       |
+| ------ | -------------- |
+| A      | Small projects |
+| B      | Large projects |
+```
+
+Why: single lookup block sits directly under the intro without a heading.
+
+## Incorrect — First of Multiple Lookup Blocks Has No Heading
+
+```markdown
+# Option Reference
+
+Use this reference to look up the supported project sizes and the review gates each one requires.
+
+| Option | Use Case       |
+| ------ | -------------- |
+| A      | Small projects |
+| B      | Large projects |
+
+## Review Gates
+
+Each size carries a different approval bar.
+
+| Option | Approvals |
+| ------ | --------- |
+| A      | 1         |
+| B      | 2         |
+```
+
+Why: the reference has two lookup blocks but only the second is headed, so the first table reads as part of the intro and cannot be scanned or linked as a group of its own.
+
+## Correct — Every Lookup Block Has a Heading
+
+```markdown
+# Option Reference
+
+Use this reference to look up the supported project sizes and the review gates each one requires.
+
+## Project Sizes
+
+Pick the size that matches the team's headcount and timeline.
+
+| Option | Use Case       |
+| ------ | -------------- |
+| A      | Small projects |
+| B      | Large projects |
+
+## Review Gates
+
+Each size carries a different approval bar.
+
+| Option | Approvals |
+| ------ | --------- |
+| A      | 1         |
+| B      | 2         |
+```
+
+Why: both lookup blocks are headed, so they read as peers and each is independently scannable and linkable.

package/docs/documentation-guide/rules/rule-creation-rule.md

@@ -0,0 +1,81 @@
+# Rule Creation Rule
+
+Rules without a consistent creation process invent their own structure and enforcement language. This rule defines how to create a Rule document.
+
+- Rule file names MUST match the document title in kebab-case and use the `-rule` suffix (e.g., `foo-rule.md`).
+- A Rule MUST contain at least one bullet point that uses [RFC 2119 vocabulary](https://datatracker.ietf.org/doc/html/rfc2119) (`MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, `MAY`).
+- RFC 2119 vocabulary MUST appear only in bullet points, so the bullet list is the single place a requirement is stated.
+- Prose outside bullet points — intros, `Why:` explanations, table cells, and code comments — MUST restate a requirement in plain language instead of repeating RFC 2119 vocabulary.
+- `MUST` MUST mean required.
+- `MUST NOT` MUST mean forbidden.
+- `SHOULD` MUST mean recommended, with exceptions possible.
+- `SHOULD NOT` MUST mean discouraged, with exceptions possible.
+- `MAY` MUST mean optional.
+- A Rule MUST contain at least one Incorrect/Correct pair.
+- A Rule MAY contain multiple Incorrect/Correct pairs.
+- An Incorrect/Correct pair MUST add a concise description after an em dash in both headings, so readers can scan the examples by decision.
+- A Rule MUST NOT link to References, Guides, or other Rules.
+
+## Incorrect — Lowercase Requirement Words
+
+```markdown
+- Authors must remove unused sections.
+- New docs should use the -rule suffix.
+```
+
+Why: lower-case "must" and "should" do not carry RFC 2119 meaning.
+
+## Correct — RFC 2119 Requirement Words
+
+```markdown
+- Authors MUST remove unused sections.
+- New docs SHOULD use the -rule suffix.
+```
+
+Why: uppercase keywords carry their canonical RFC 2119 meaning.
+
+## Incorrect — Rule Links to a Reference
+
+```markdown
+- Rule bodies MUST follow the guidance in the [Vocabulary Reference](../references/vocabulary-reference.md).
+```
+
+Why: rule contains a reference to another Reference.
+
+## Correct — Rule States Its Vocabulary Directly
+
+```markdown
+- Rule bodies MUST use RFC 2119 vocabulary: MUST, MUST NOT, SHOULD, SHOULD NOT, or MAY.
+```
+
+Why: rule states requirements directly without referencing other docs.
+
+## Incorrect — Requirement Repeated in an Explanation
+
+```markdown
+- A helper file MUST use named exports.
+
+## Incorrect — Default Export
+
+// helper.ts
+export default function sum(a, b) {}
+
+Why: a helper file MUST use named exports, so `export default` is not allowed here.
+```
+
+Why: the explanation repeats the bullet's requirement word, so the requirement now lives in two places and a later edit can leave the bullet and the explanation disagreeing about what is required.
+
+## Correct — Requirement Explained in Plain Language
+
+```markdown
+- A helper file MUST use named exports.
+
+## Incorrect — Default Export
+
+// helper.ts
+export default function sum(a, b) {}
+
+Why: helper files use named exports only, so `export default` does not belong here.
+```
+
+Why: the bullet is the only place the requirement is stated, and the explanation describes the example in plain language.

package/docs/documentation-guide/rules/template-usage-rule.md

@@ -0,0 +1,48 @@
+# Template Usage Rule
+
+Authoring without a template makes every doc invent its own title, orientation, and section shape. This rule keeps new docs predictable. Templates for each document kind live in `../_templates/`.
+
+- Authors MUST start from the template for the chosen document kind.
+- Authors MUST replace each bracketed prompt with the final title, explanation, step, or lookup content it asks for.
+- Authors MUST delete template branches that do not apply to the document being written.
+
+## Incorrect — Template Prompts and Unused Branches Kept
+
+```markdown
+# Example Guide
+
+[1-2 short sentences explaining the underlying idea behind this guide and why it matters.]
+
+## How To Do Something
+
+[What does this accomplish? When should it run?]
+
+1. [Step 1]
+2. [Step 2]
+
+## How To Another Workflow
+
+[What does this accomplish? When should it run?]
+
+1. [Step 1]
+2. [Step 2]
+```
+
+Why: committed doc still contains bracketed prompts, and the unused "Another Workflow" section was not deleted.
+
+## Correct — Template Prompts Replaced and Unused Branches Removed
+
+```markdown
+# Example Guide
+
+This guide shows how to do something useful. It matters because doing it wrong breaks the build.
+
+## How To Do Something
+
+Run this before every release.
+
+1. Check the config.
+2. Run the deploy script.
+```
+
+Why: all bracketed prompts are replaced, unused template branches are deleted, and no leftover brackets remain.