pasika 0.6.0 → 0.7.0

package/README.md

@@ -191,7 +191,7 @@ Applied to `src/**/globals.css` (and other stylesheets) through `@eslint/css` wi
 | `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/skin-utility`             | Repeated style combinations become a named skin utility                                               |
 | `pasika/theme-variable-namespace` | Utility class groups share a namespace prefix                                                         |
 | `pasika/css-entry-point` †        | One global entry, imported by one module, project CSS only in a stylesheet the entry imports directly |
 | `pasika/unused-utility`           | A custom `@utility` no source file references is reported as dead                                     |

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

@@ -98,6 +98,7 @@ declare const documentationRules: {
     "no-nested-how-to": _eslint_markdown.MarkdownRuleDefinition;
     "glossary-term-linking": _eslint_markdown.MarkdownRuleDefinition;
     "guide-mentions-documents": _eslint_markdown.MarkdownRuleDefinition;
+    "guide-section-shape": _eslint_markdown.MarkdownRuleDefinition;
 };
 
 declare const tailwindRules: {
@@ -108,7 +109,7 @@ declare const tailwindRules: {
     "stylesheet-ordering": _eslint_css.CSSRuleDefinition;
     "css-variable-naming": _eslint_css.CSSRuleDefinition;
     "custom-utility-apply": _eslint_css.CSSRuleDefinition;
-    "surface-utility": _eslint_css.CSSRuleDefinition;
+    "skin-utility": _eslint_css.CSSRuleDefinition;
     "theme-variable-namespace": _eslint_css.CSSRuleDefinition;
     "css-entry-point": _eslint_css.CSSRuleDefinition;
     "global-stylesheet": _eslint_css.CSSRuleDefinition;
@@ -158,7 +159,7 @@ declare const pasikaPlugin: {
         "stylesheet-ordering": _eslint_css.CSSRuleDefinition;
         "css-variable-naming": _eslint_css.CSSRuleDefinition;
         "custom-utility-apply": _eslint_css.CSSRuleDefinition;
-        "surface-utility": _eslint_css.CSSRuleDefinition;
+        "skin-utility": _eslint_css.CSSRuleDefinition;
         "theme-variable-namespace": _eslint_css.CSSRuleDefinition;
         "css-entry-point": _eslint_css.CSSRuleDefinition;
         "global-stylesheet": _eslint_css.CSSRuleDefinition;
@@ -186,6 +187,7 @@ declare const pasikaPlugin: {
         "no-nested-how-to": _eslint_markdown.MarkdownRuleDefinition;
         "glossary-term-linking": _eslint_markdown.MarkdownRuleDefinition;
         "guide-mentions-documents": _eslint_markdown.MarkdownRuleDefinition;
+        "guide-section-shape": _eslint_markdown.MarkdownRuleDefinition;
         "filename-case": eslint.Rule.RuleModule;
         "import-boundaries": eslint.Rule.RuleModule;
         "named-exports": eslint.Rule.RuleModule;

package/dist/eslint/pasika/index.js

@@ -174,7 +174,9 @@ function findSimpleRoot(component, _text, _filename) {
   };
   visit(body);
   const rendered = returns.filter((statement) => statement.expression?.kind !== ts.SyntaxKind.NullKeyword);
-  const roots = rendered.map((statement) => statement.expression && ts.isExpression(statement.expression) ? rootFromExpression(statement.expression) : void 0).filter((root) => root !== void 0);
+  const roots = rendered.map(
+    (statement) => statement.expression && ts.isExpression(statement.expression) ? rootFromExpression(statement.expression) : void 0
+  ).filter((root) => root !== void 0);
   if (roots.length !== rendered.length || roots.length === 0) return void 0;
   const firstTag = roots[0]?.tagName;
   if (roots.some((root) => root.tagName !== firstTag)) return void 0;
@@ -2302,7 +2304,17 @@ var NEXT_ROUTING_FILES3 = /* @__PURE__ */ new Set([
   "sitemap",
   "twitter-image"
 ]);
-var INTERACTIVE_ATTRIBUTES = /* @__PURE__ */ new Set(["onClick", "onChange", "onSubmit", "href", "onKeyDown", "onKeyUp", "onFocus", "onBlur", "htmlFor"]);
+var INTERACTIVE_ATTRIBUTES = /* @__PURE__ */ new Set([
+  "onClick",
+  "onChange",
+  "onSubmit",
+  "href",
+  "onKeyDown",
+  "onKeyUp",
+  "onFocus",
+  "onBlur",
+  "htmlFor"
+]);
 function tagName(node) {
   const name = node.openingElement?.name;
   if (name?.type !== "JSXIdentifier") return void 0;
@@ -2375,7 +2387,9 @@ function isDecorative(node) {
   return !meaningfulText && !isContentElement(name);
 }
 function isContentElement(name) {
-  return /^(?:h[1-6]|p|li|dt|dd|blockquote|pre|code|figcaption|caption|th|td|form|fieldset|select|textarea)$/.test(name);
+  return /^(?:h[1-6]|p|li|dt|dd|blockquote|pre|code|figcaption|caption|th|td|form|fieldset|select|textarea)$/.test(
+    name
+  );
 }
 function isSoleContentOfWrapper(node) {
   const parent = node.parent;
@@ -3667,11 +3681,7 @@ function combosFor(index) {
   const files = [...index.modules.keys()].filter((file) => file.endsWith(".tsx") || file.endsWith(".jsx")).sort((left, right) => left.localeCompare(right));
   let fingerprint2 = "";
   for (const file of files) {
-    try {
-      fingerprint2 += String(statSync3(file).mtimeMs);
-    } catch {
-      fingerprint2 += "0";
-    }
+    fingerprint2 += String(statSync3(file).mtimeMs);
   }
   if (comboCache?.sourceRoot === index.sourceRoot && comboCache.fingerprint === fingerprint2) {
     return comboCache.combos;
@@ -3696,7 +3706,7 @@ var sharedStyleDedupRule = {
     schema: [],
     type: "problem",
     docs: {
-      description: "Require a className combination used by two or more components to become a named custom utility."
+      description: "Require a className combination used by two or more components to become a named *-skin utility."
     }
   },
   create(context) {
@@ -3715,7 +3725,7 @@ var sharedStyleDedupRule = {
           context.report({
             node,
             loc: { line: 1, column: 0 },
-            message: `Class combination "${combo}" is used by ${String(users.size)} components and should change together; create a named custom Tailwind utility for it. See docs/next-tailwind-guide/rules/theme-and-utility-definition-rule.md`
+            message: `Class combination "${combo}" is used by ${String(users.size)} components and should change together; create a named *-skin Tailwind utility for it. See docs/next-tailwind-guide/rules/theme-and-utility-definition-rule.md`
           });
         }
       }
@@ -4153,7 +4163,7 @@ var overviewRule = {
   meta: {
     type: "problem",
     docs: {
-      description: "Overview must exist, contain at most two sentences, and not link to other documents.",
+      description: "Required documentation overviews must exist, contain at most two sentences, and not link to other documents.",
       recommended: true
     }
   },
@@ -4196,6 +4206,41 @@ var overviewRule = {
         if (!found) {
           context.report({ node, message: "no overview follows the title" });
         }
+        const validateHeadedOverview = (heading, index, label) => {
+          const overview = node.children[index + 1];
+          if (overview?.type !== "paragraph") {
+            context.report({
+              node: heading,
+              message: `no overview follows ${label}`
+            });
+            return;
+          }
+          if (containsLink(overview)) {
+            context.report({
+              node: overview,
+              message: `overview of ${label} links another document`
+            });
+          }
+          const sectionSentenceCount = countSentences(getTextContent(overview).trim());
+          if (sectionSentenceCount > 2) {
+            context.report({
+              node: overview,
+              message: `overview of ${label} uses ${String(sectionSentenceCount)} sentences, at most two are allowed`
+            });
+          }
+        };
+        const isGuide = filename.endsWith("-guide.md");
+        const isReference = filename.endsWith("-reference.md");
+        if (!isGuide && !isReference) return;
+        for (const [index, child] of node.children.entries()) {
+          if (child.type !== "heading" || child.depth === 1) continue;
+          const title = getTextContent(child).trim();
+          if (isGuide && child.depth === 2 && /^How To \S/.test(title)) {
+            validateHeadedOverview(child, index, `guide section "${title}"`);
+          } else if (isReference) {
+            validateHeadedOverview(child, index, `reference block "${title}"`);
+          }
+        }
       }
     };
   }
@@ -5049,6 +5094,56 @@ var guideMentionsDocumentsRule = {
   }
 };
 
+// eslint/rules/documentation/guide-section-shape.ts
+var guideSectionShapeRule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Guide sections use How To headings, an overview, and numbered steps.",
+      recommended: true
+    }
+  },
+  create(context) {
+    return {
+      root(node) {
+        if (!getFilename(context).endsWith("-guide.md")) return;
+        const sections = [];
+        for (const [index, child] of node.children.entries()) {
+          if (child.type !== "heading" || child.depth === 1) continue;
+          sections.push({ heading: child, index, title: getTextContent(child).trim() });
+        }
+        if (sections.length === 0) {
+          context.report({ node, message: "guide must contain at least one How To section" });
+          return;
+        }
+        for (const [sectionIndex, section] of sections.entries()) {
+          if (section.heading.depth !== 2) {
+            context.report({
+              node: section.heading,
+              message: `guide section heading "${section.title}" must be level two`
+            });
+          }
+          if (!/^How To \S/.test(section.title)) {
+            context.report({
+              node: section.heading,
+              message: `guide section heading "${section.title}" must start with "How To "`
+            });
+          }
+          const nextSection = sections[sectionIndex + 1];
+          const content = node.children.slice(section.index + 1, nextSection?.index ?? node.children.length);
+          const hasOverviewThenNumberedList = content.length === 2 && content[0]?.type === "paragraph" && content[1]?.type === "list" && content[1].ordered === true;
+          if (!hasOverviewThenNumberedList) {
+            context.report({
+              node: section.heading,
+              message: `guide section "${section.title}" must consist of its overview followed by one numbered list`
+            });
+          }
+        }
+      }
+    };
+  }
+};
+
 // eslint/rules/documentation/index.ts
 var documentationRules = {
   "doc-kind-suffix": docKindSuffixRule,
@@ -5073,7 +5168,8 @@ var documentationRules = {
   "guide-link-anchors": guideLinkAnchorsRule,
   "no-nested-how-to": noNestedHowToRule,
   "glossary-term-linking": glossaryTermLinkingRule,
-  "guide-mentions-documents": guideMentionsDocumentsRule
+  "guide-mentions-documents": guideMentionsDocumentsRule,
+  "guide-section-shape": guideSectionShapeRule
 };
 
 // eslint/rules/tailwind/helpers.ts
@@ -5341,12 +5437,18 @@ var stylesheetOrderingRule = {
 };
 
 // eslint/rules/tailwind/css-variable-naming.ts
+var EDGE_PROPERTY_WORDS = /* @__PURE__ */ new Set(["border", "divider", "outline", "ring", "stroke"]);
+var NON_COLOR_WORDS = /* @__PURE__ */ new Set(["offset", "radius", "spacing", "style", "width"]);
+function looksLikeEdgeColor(lower) {
+  const words = lower.slice(2).split("-");
+  return words.some((word) => EDGE_PROPERTY_WORDS.has(word)) && !words.some((word) => NON_COLOR_WORDS.has(word));
+}
 var cssVariableNamingRule = {
   meta: {
     schema: [],
     type: "problem",
     docs: {
-      description: "Require background variables to end in -canvas and text variables to end in -ink."
+      description: "Require property-specific color variables to use canvas, ink, and edge role suffixes."
     }
   },
   create(context) {
@@ -5367,6 +5469,12 @@ var cssVariableNamingRule = {
             message: `CSS variable "${property}" looks like a text token; name it --<role>-ink instead.`
           });
         }
+        if (looksLikeEdgeColor(lower) && !lower.endsWith("-edge")) {
+          context.report({
+            node,
+            message: `CSS variable "${property}" looks like a boundary token; name it --<role>-edge instead.`
+          });
+        }
       }
     };
   }
@@ -5414,24 +5522,31 @@ var customUtilityApplyRule = {
   }
 };
 
-// eslint/rules/tailwind/surface-utility.ts
-var surfaceUtilityRule = {
+// eslint/rules/tailwind/skin-utility.ts
+var skinUtilityRule = {
   meta: {
     schema: [],
     type: "problem",
     docs: {
-      description: "Require repeated canvas+ink combinations to become a *-surface utility."
+      description: "Require reusable style combinations to become *-skin utilities."
     }
   },
   create(context) {
     return {
       "StyleSheet:exit"(node) {
+        for (const utility of atrulesNamed(node, "utility")) {
+          const name = preludeIdentifiers(utility)[0];
+          const applied = new Set(atrulesNamed(utility, "apply").flatMap((apply) => preludeIdentifiers(apply)));
+          if (applied.size < 2 || name?.endsWith("-skin") === true) continue;
+          context.report({
+            node: utility,
+            message: `Custom utility "${name ?? "unknown"}" combines ${String(applied.size)} styles; use the *-skin suffix.`
+          });
+        }
         const combinations = /* @__PURE__ */ new Map();
         for (const apply of atrulesNamed(node, "apply")) {
           const classes = preludeIdentifiers(apply);
-          if (!classes.some((name) => name.includes("canvas")) || !classes.some((name) => name.includes("ink"))) {
-            continue;
-          }
+          if (new Set(classes).size < 2) continue;
           const key = [...classes].sort().join(" ");
           combinations.set(key, (combinations.get(key) ?? 0) + 1);
         }
@@ -5439,7 +5554,7 @@ var surfaceUtilityRule = {
           if (count < 2) continue;
           context.report({
             node,
-            message: `Combination "${combo}" appears ${String(count)} times. Create a *-surface custom Tailwind utility for it.`
+            message: `Combination "${combo}" appears ${String(count)} times. Create a *-skin custom Tailwind utility for it.`
           });
         }
       }
@@ -5739,7 +5854,7 @@ var tailwindRules = {
   "stylesheet-ordering": stylesheetOrderingRule,
   "css-variable-naming": cssVariableNamingRule,
   "custom-utility-apply": customUtilityApplyRule,
-  "surface-utility": surfaceUtilityRule,
+  "skin-utility": skinUtilityRule,
   "theme-variable-namespace": themeVariableNamespaceRule,
   "css-entry-point": cssEntryPointRule,
   "global-stylesheet": globalStylesheetRule,
@@ -6374,9 +6489,7 @@ var tailwindStructureRules = {
   },
   language: "css/css",
   languageOptions: { tolerant: true },
-  rules: Object.fromEntries(
-    tailwindRuleIds.filter((id) => id !== "pasika/css-entry-point").map((id) => [id, "error"])
-  )
+  rules: Object.fromEntries(tailwindRuleIds.filter((id) => id !== "pasika/css-entry-point").map((id) => [id, "error"]))
 };
 var tailwindImportGraph = {
   files: ["src/**/*.css"],
@@ -6424,11 +6537,7 @@ var documentationConfig = {
   language: "markdown/gfm",
   rules: Object.fromEntries(documentationRuleIds.map((id) => [id, "error"]))
 };
-var pasikaApp = [
-  pasikaAppPackageJsonConfig,
-  zirkaConfig,
-  documentationConfig
-];
+var pasikaApp = [pasikaAppPackageJsonConfig, zirkaConfig, documentationConfig];
 var pasikaNextjsAppWithDiagnostic = (preset) => {
   let checked = false;
   return new Proxy(preset, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pasika",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Reusable agent setup package",
   "repository": {
     "type": "git",
@@ -62,7 +62,7 @@
     "tsx": "4.23.12",
     "typescript": "6.0.3",
     "vitest": "5.0.0",
-    "zirka": "0.0.48",
+    "zirka": "0.0.65",
     "zod": "4.4.3"
   },
   "peerDependencies": {