vigiles 2.6.0 → 4.0.0

package/skills/linter-docs/stylelint.md

@@ -0,0 +1,247 @@
+# Stylelint — Reference
+
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom rules).
+
+## Check Existing Plugins First
+
+Before writing a custom rule, search these packages — the pattern may already be covered:
+
+| Plugin                                      | Scope                    | Key rules                                                                                                                                   |
+| ------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `stylelint-config-standard`                 | Standard CSS conventions | Extends `stylelint-config-recommended`, adds `declaration-block-no-redundant-longhand-properties`, `shorthand-property-no-redundant-values` |
+| `stylelint-config-recommended`              | Error prevention         | `no-descending-specificity`, `no-duplicate-selectors`, `declaration-block-no-duplicate-properties`                                          |
+| `stylelint-order`                           | Property ordering        | `order/properties-order`, `order/properties-alphabetical-order` — configurable sort orders                                                  |
+| `stylelint-scss`                            | SCSS syntax              | `scss/no-duplicate-mixins`, `scss/no-unused-private-members`, `scss/at-rule-no-unknown`, `scss/dollar-variable-pattern`                     |
+| `stylelint-config-css-modules`              | CSS Modules              | Adjusts rules for `:global`, `:local`, `composes` syntax                                                                                    |
+| `stylelint-config-tailwindcss`              | Tailwind CSS             | Allows Tailwind directives (`@tailwind`, `@apply`, `@screen`)                                                                               |
+| `stylelint-no-unsupported-browser-features` | Browser compat           | Flags CSS features not supported by your browserslist targets                                                                               |
+| `stylelint-declaration-strict-value`        | Value enforcement        | Require variables/functions for specific properties (colors, fonts, z-index)                                                                |
+| `stylelint-config-clean-order`              | Property order           | Opinionated property ordering (positioning → box model → typography → visual → misc)                                                        |
+| `stylelint-config-prettier`                 | Prettier compat          | Disables rules that conflict with Prettier (deprecated in Stylelint v15+)                                                                   |
+| `stylelint-a11y`                            | Accessibility            | `a11y/no-outline-none`, `a11y/no-text-size-adjust`, `a11y/media-prefers-reduced-motion`                                                     |
+
+**Tip:** Stylelint v15+ removed all stylistic rules (spacing, formatting). Use Prettier for formatting, Stylelint for correctness.
+
+## Rule Anatomy
+
+Every Stylelint rule is a function that receives options and returns a checker:
+
+```js
+const stylelint = require("stylelint");
+
+const ruleName = "plugin/no-important";
+const messages = stylelint.utils.ruleMessages(ruleName, {
+  rejected: "Unexpected !important — use utility classes instead.",
+});
+const meta = { url: "https://example.com/rules/no-important" };
+
+/** @type {import('stylelint').Rule} */
+const ruleFunction = (primary, secondary, context) => {
+  return (root, result) => {
+    const validOptions = stylelint.utils.validateOptions(result, ruleName, {
+      actual: primary,
+      possible: [true],
+    });
+    if (!validOptions) return;
+
+    root.walkDecls((decl) => {
+      if (decl.important) {
+        stylelint.utils.report({
+          message: messages.rejected,
+          node: decl,
+          result,
+          ruleName,
+        });
+      }
+    });
+  };
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+ruleFunction.meta = meta;
+
+module.exports = stylelint.createPlugin(ruleName, ruleFunction);
+```
+
+### Key concepts
+
+| Concept                             | Purpose                                    | Notes                                                     |
+| ----------------------------------- | ------------------------------------------ | --------------------------------------------------------- |
+| `primary`                           | First option (usually `true` or a pattern) | What the user passes in config                            |
+| `secondary`                         | Second option (usually an object)          | Additional configuration                                  |
+| `context`                           | Execution context                          | Contains `fix` boolean for auto-fix mode                  |
+| `root`                              | PostCSS AST root node                      | Entry point for walking the CSS tree                      |
+| `result`                            | Results accumulator                        | Pass to `stylelint.utils.report()`                        |
+| `stylelint.utils.report()`          | Report a violation                         | Canonical way to report — handles severity, ignores, etc. |
+| `stylelint.utils.validateOptions()` | Validate rule config                       | Returns false if config is invalid                        |
+
+### PostCSS AST node types
+
+| Node type     | What it represents      | Walker method         | Example                     |
+| ------------- | ----------------------- | --------------------- | --------------------------- |
+| `Root`        | Entire stylesheet       | —                     | Top-level container         |
+| `Rule`        | Selector + declarations | `root.walkRules()`    | `.button { color: red }`    |
+| `Declaration` | Property: value pair    | `root.walkDecls()`    | `color: red`                |
+| `AtRule`      | `@` rule                | `root.walkAtRules()`  | `@media (min-width: 768px)` |
+| `Comment`     | CSS comment             | `root.walkComments()` | `/* comment */`             |
+
+Properties on `Declaration`: `decl.prop` (property name), `decl.value` (value string), `decl.important` (boolean).
+
+## Configuration
+
+### `.stylelintrc.json`
+
+```json
+{
+  "extends": ["stylelint-config-standard"],
+  "plugins": ["stylelint-order"],
+  "rules": {
+    "declaration-no-important": true,
+    "selector-max-specificity": "0,3,0",
+    "order/properties-alphabetical-order": true
+  }
+}
+```
+
+### `stylelint.config.js` (flat config)
+
+```js
+module.exports = {
+  extends: ["stylelint-config-standard"],
+  rules: {
+    "declaration-no-important": true,
+  },
+  overrides: [
+    {
+      files: ["**/*.scss"],
+      extends: ["stylelint-config-standard-scss"],
+    },
+  ],
+};
+```
+
+### Key config concepts
+
+- **`extends`** — inherit from shared configs (order matters — later overrides earlier)
+- **`plugins`** — load additional rule packages
+- **`rules`** — enable/disable/configure individual rules (`true`, `null`, or `[value, options]`)
+- **`overrides`** — per-file rule configuration (like ESLint overrides)
+
+## Testing Rules
+
+```js
+const { lint } = require("stylelint");
+
+async function testRule() {
+  const result = await lint({
+    code: "a { color: pink !important; }",
+    config: {
+      plugins: ["./plugin-no-important.js"],
+      rules: { "plugin/no-important": true },
+    },
+  });
+
+  console.log(result.results[0].warnings);
+  // [{ rule: "plugin/no-important", text: "Unexpected !important...", line: 1, column: 19 }]
+}
+```
+
+For plugin development, use `jest-preset-stylelint` or test via `lint()` directly.
+
+**Testing best practices:**
+
+1. **Test with `lint()` API** — canonical method, works with any test runner
+2. **Test valid and invalid cases** — ensure no false positives
+3. **Test with SCSS/Less** if the plugin should support preprocessor syntax
+4. **Test `overrides`** — if the rule has options, test each configuration
+
+### vigiles enforce() reference
+
+```typescript
+enforce("stylelint/declaration-no-important", "Use utility classes instead.");
+enforce(
+  "stylelint/selector-max-specificity",
+  "Keep specificity low for maintainability.",
+);
+```
+
+vigiles loads Stylelint config via `createLinter` + `getConfigForFile`, checks if the rule value is not `null`.
+
+## Edge Cases and Gotchas
+
+### CSS-in-JS
+
+Stylelint supports CSS-in-JS via custom syntaxes:
+
+```json
+{
+  "overrides": [
+    {
+      "files": ["**/*.{js,jsx,ts,tsx}"],
+      "customSyntax": "@stylelint/postcss-css-in-js"
+    }
+  ]
+}
+```
+
+Note: `@stylelint/postcss-css-in-js` is deprecated as of Stylelint v15. For styled-components / emotion, consider `postcss-styled-syntax` or lint extracted CSS instead.
+
+### SCSS / Less
+
+Use dedicated configs:
+
+- SCSS: `stylelint-config-standard-scss` (includes `stylelint-scss` plugin)
+- Less: `postcss-less` as `customSyntax`
+
+SCSS nesting (`&-modifier`) and mixins may trigger false positives in standard rules. The SCSS config handles this.
+
+### Prettier conflicts (v15+)
+
+Stylelint v15 removed all stylistic rules. If upgrading from v14:
+
+- Remove `stylelint-config-prettier` (no longer needed)
+- Remove manual disables of formatting rules (`indentation`, `string-quotes`, etc.)
+- Stylelint now handles correctness only; Prettier handles formatting
+
+### Property order plugins
+
+`stylelint-order` and `stylelint-config-clean-order` can conflict. Use one ordering strategy:
+
+- Alphabetical: `order/properties-alphabetical-order`
+- Grouped: `order/properties-order` with a custom group list
+- Clean order: extend `stylelint-config-clean-order` (opinionated groups)
+
+### `extends` order matters
+
+```json
+{
+  "extends": ["stylelint-config-standard", "stylelint-config-prettier"]
+}
+```
+
+Later configs override earlier ones. Put base configs first, overrides last.
+
+### Monorepo considerations
+
+- Stylelint resolves config from the file being linted, walking up directories
+- Each package can have its own `.stylelintrc.json`
+- vigiles checks Stylelint config via `createLinter({ cwd: basePath })` — in a monorepo, run from each package root
+
+## Mapping PR Feedback to Rule Strategy
+
+| PR comment pattern           | Best approach                                                                     |
+| ---------------------------- | --------------------------------------------------------------------------------- |
+| "Don't use !important"       | `stylelint/declaration-no-important` — already exists                             |
+| "Keep specificity low"       | `stylelint/selector-max-specificity` with threshold                               |
+| "Sort properties"            | `stylelint-order` plugin — `order/properties-alphabetical-order` or custom groups |
+| "Don't use ID selectors"     | `stylelint/selector-max-id` — already exists                                      |
+| "Use variables for colors"   | `stylelint-declaration-strict-value` plugin                                       |
+| "No vendor prefixes"         | `stylelint/property-no-vendor-prefix`, `value-no-vendor-prefix`                   |
+| "Don't nest too deep"        | `stylelint/selector-max-compound-selectors` with threshold                        |
+| "Use modern CSS"             | `stylelint/declaration-property-value-no-unknown` + browserslist                  |
+| "Remove empty blocks"        | `stylelint/block-no-empty` — already exists                                       |
+| "Don't duplicate properties" | `stylelint/declaration-block-no-duplicate-properties` — already exists            |
+| "Use shorthand"              | `stylelint/declaration-block-no-redundant-longhand-properties` — already exists   |
+| "Font naming convention"     | `stylelint/font-family-name-quotes` — already exists                              |
+| "No unknown @rules"          | `stylelint/at-rule-no-unknown` (or `scss/at-rule-no-unknown` for SCSS)            |

package/skills/migrate-to-spec/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: migrate-to-spec
+description: Convert an existing hand-written CLAUDE.md into a typed .spec.ts file for incremental adoption
+disable-model-invocation: true
+argument-hint: <path to CLAUDE.md, defaults to CLAUDE.md>
+---
+
+Convert an existing hand-written CLAUDE.md (or AGENTS.md) into a typed `CLAUDE.md.spec.ts` file. This is the incremental adoption path — you keep your existing instruction file as the starting point and get type safety going forward.
+
+> **Don't need full TypeScript?** A typed spec is the deepest commitment level. If the user only wants verified rules without a build step, point them at markdown mode first: inline `<!-- vigiles:enforce ... -->` comments (Level 0) or a `vigiles:` YAML frontmatter block with `vigiles generate-schema` for editor autocomplete (Level 1). Both are verified by `vigiles audit` with the same engine as a spec. See `docs/markdown-mode.md`. Migrate to a spec only when they want compiler-grade guarantees.
+
+## Instructions
+
+### Step 1: Read the Existing File
+
+Read the target instruction file (default: `CLAUDE.md` in the repo root). If the user specified a path, use that.
+
+Also check if vigiles is installed: look for `vigiles` in `package.json` devDependencies. If not, suggest:
+
+```bash
+npm install -D vigiles
+```
+
+### Step 2: Parse the Structure
+
+Identify these sections in the markdown:
+
+- **Commands** — lines like `` `npm run build` — description `` or ``- `command` — description``
+- **Key files** — lines like `` `src/foo.ts` — description `` listing important files
+- **Rules** — `###` headings with `**Enforced by:**` or `**Guidance only**` annotations
+- **Prose sections** — everything else (positioning, architecture, principles, etc.)
+
+For each rule, classify it:
+
+- Has `**Enforced by:** \`linter/rule\``→`enforce("linter/rule", "why")`
+- Has `**Enforced by:** \`code-review\``or similar non-linter →`guidance("...")`
+- Has `**Guidance only**` → `guidance("...")`
+- Has no annotation → mark as TODO for the user to classify
+
+### Step 3: Generate the Spec File
+
+Create `CLAUDE.md.spec.ts` (or the appropriate name based on the source file) with this structure:
+
+```typescript
+import {
+  claude,
+  enforce,
+  guidance,
+  check,
+  every,
+  file,
+  cmd,
+  ref,
+  instructions,
+} from "vigiles/spec";
+
+export default claude({
+  sections: {
+    // Prose sections here
+  },
+
+  keyFiles: {
+    // Key files here
+  },
+
+  commands: {
+    // Commands here
+  },
+
+  rules: {
+    // Rules here
+  },
+});
+```
+
+**Important guidelines:**
+
+- Use `file()` refs in sections where file paths appear in backticks — this enables stale reference detection
+- Use `cmd()` refs for any `npm run` commands mentioned in sections
+- Convert `**Enforced by:** \`code-review\``rules to`guidance()` — code review is not a mechanical enforcement
+- For rules with no annotation, add a `// TODO: classify as enforce() or guidance()` comment
+- Keep rule IDs as kebab-case versions of the heading text
+- Preserve the `**Why:**` text as the second argument to `enforce()` or `guidance()`
+- If sections reference other files or skills, use `ref()` for cross-references
+
+### Step 4: Verify the Spec Compiles
+
+Run:
+
+```bash
+npm run build
+npx vigiles compile CLAUDE.md.spec.ts
+```
+
+Compare the compiled output against the original file. Key differences are expected (formatting, section ordering), but all rules, commands, key files, and prose content should be preserved.
+
+### Step 5: Present the Result
+
+Show the user:
+
+1. The generated spec file
+2. How many rules were converted (enforce vs guidance vs TODO)
+3. How many file/cmd refs were added for stale reference detection
+4. The command to compile: `npx vigiles compile`
+5. The command to verify: `npx vigiles check`
+
+Ask if they want you to write the file. If yes, also suggest adding to `.gitignore` or updating CI to run `vigiles compile` and `vigiles check`.
+
+### Step 6: Optional — Set Up CI
+
+If the user wants CI integration, suggest adding to their GitHub Actions workflow:
+
+```yaml
+- name: Compile specs
+  run: npx vigiles compile
+- name: Verify integrity
+  run: npx vigiles check
+```
+
+Or using the vigiles GitHub Action:
+
+```yaml
+- uses: zernie/vigiles@main
+  with:
+    command: check
+```

package/skills/strengthen/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: strengthen
+description: Upgrade guidance() rules to enforce() by finding existing linter rules that match
+disable-model-invocation: true
+---
+
+Scan spec files for `guidance()` rules and suggest `enforce()` replacements backed by real linter rules.
+
+## Instructions
+
+### Step 0: Choose Mode
+
+Ask the user:
+
+> **Auto or interactive?**
+>
+> - **Auto** — I'll apply all safe changes (direct replacements where the rule is already enabled), commit, and show you the diff. Risky changes (require config edits or plugin installs) go in a summary for you to review.
+> - **Interactive** — I'll present each suggestion and you pick which ones to apply.
+
+Default to interactive if the user doesn't specify.
+
+### Step 1: Discover What's Installed
+
+Run `npx vigiles generate-types` to get the full list of enabled linter rules in the project. Read `.vigiles/generated.d.ts` to see every rule available across all detected linters.
+
+Note which linter prefixes appear in the generated types (e.g., `EslintRule`, `RuffRule`). You'll only need reference docs for detected linters.
+
+### Step 2: Find All Guidance Rules
+
+Find all `.spec.ts` files in the project (`**/*.md.spec.ts`). For each file, identify every `guidance()` rule.
+
+### Step 3: Match Against Generated Types (Fast Path)
+
+For each guidance rule, check if an enabled rule in `.vigiles/generated.d.ts` directly matches. This is the fast, deterministic path — no doc reading needed.
+
+Look for:
+
+- **Exact rule name in text** — guidance says "no-console" and `no-console` is in EslintRule
+- **Semantic match** — guidance says "don't use console.log" and `no-console` is available
+- **Rule description match** — guidance says "unused variables" and `no-unused-vars` or `@typescript-eslint/no-unused-vars` is available
+
+If a match is found and the rule is in the generated types (meaning it's already enabled), this is a **direct replacement** — no config changes needed.
+
+### Step 4: Read Linter Docs (Slow Path)
+
+For guidance rules that didn't match in Step 3, read the linter reference docs for the project's detected linters:
+
+- ESLint → `../linter-docs/eslint.md`
+- Stylelint → `../linter-docs/stylelint.md`
+- Ruff → `../linter-docs/ruff.md`
+- Pylint → `../linter-docs/pylint.md`
+- RuboCop → `../linter-docs/rubocop.md`
+- Clippy → `../linter-docs/clippy.md`
+
+**Only read docs for linters the project actually uses.** Skip docs for linters with no rules in generated types.
+
+Check the plugin tables and decision matrices. The guidance text may describe a pattern covered by:
+
+- A plugin rule that's installed but not enabled
+- A plugin that's not installed yet
+- A `no-restricted-*` config pattern (see Step 4b)
+
+### Step 4b: `no-restricted-*` Patterns
+
+Many guidance rules can be enforced via built-in linter config without a custom rule. This is the most common strengthen pattern — "don't do X" maps to a restriction config.
+
+**ESLint:**
+
+```js
+// "Don't import from internal modules"
+"no-restricted-imports": ["error", {
+  patterns: [{ group: ["src/internal/*"], message: "Use the public API." }]
+}],
+
+// "Don't call console.log"
+"no-restricted-syntax": ["error", {
+  selector: 'CallExpression[callee.object.name="console"]',
+  message: "Use the project logger."
+}],
+
+// "Don't use moment.js"
+"no-restricted-imports": ["error", {
+  paths: [{ name: "moment", message: "Use dayjs instead." }]
+}],
+```
+
+**Ruff:**
+
+```toml
+# "Don't use os.system"
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"os.system".msg = "Use subprocess.run instead."
+```
+
+**RuboCop:**
+
+```yaml
+# "Don't use puts in production" — if Rails/Output doesn't fit
+Custom/NoPuts:
+  Enabled: true
+```
+
+When suggesting a `no-restricted-*` change:
+
+1. Show the exact config edit needed (which file, which section)
+2. Show the `enforce()` rule that references it
+3. Note that this changes linter config, not just the spec
+
+### Step 5: Present Suggestions
+
+Group the output into tiers:
+
+**Tier 1: Direct replacements** (rule already enabled — zero risk)
+
+```typescript
+// Before
+"no-console": guidance("Use structured logger instead of console.log"),
+// After
+"no-console": enforce("eslint/no-console", "Use structured logger instead of console.log"),
+```
+
+**Tier 2: Config-backed** (rule exists but needs config options)
+
+```typescript
+// Spec change:
+"no-moment": enforce("eslint/no-restricted-imports", "Use dayjs instead of moment."),
+
+// Config change needed (eslint.config.mjs):
+"no-restricted-imports": ["error", {
+  paths: [{ name: "moment", message: "Use dayjs instead." }]
+}],
+```
+
+**Tier 3: Plugin install needed**
+
+```
+"cognitive-complexity": guidance("Keep functions simple")
+→ Install eslint-plugin-sonarjs, enable sonarjs/cognitive-complexity
+→ enforce("eslint/sonarjs/cognitive-complexity", "Keep functions simple")
+```
+
+**Tier 4: No match** (stays as guidance, or candidate for `/pr-to-lint-rule`)
+
+```
+"research-first": guidance("Google unfamiliar APIs first.")
+→ No linter rule can enforce this. Stays as guidance.
+→ Want me to run /pr-to-lint-rule to create a custom rule?
+```
+
+### Step 6: Apply Changes
+
+**In auto mode:**
+
+1. Apply all Tier 1 changes (edit spec files, replace `guidance()` with `enforce()`)
+2. Run `npm run build && npx vigiles compile` to verify each change compiles
+3. If any compilation fails, revert that specific change and report the error
+4. Commit all successful changes
+5. Present Tier 2-4 as a summary for the user to review
+
+**In interactive mode:**
+
+1. Present all tiers
+2. Ask the user which suggestions to apply
+3. For approved Tier 2 changes: edit the linter config, then edit the spec
+4. Run `npm run build && npx vigiles compile` to verify
+5. If compilation fails, report the error and revert
+
+**For Tier 4 (no match):** Ask the user if they want to run `/pr-to-lint-rule` for any of the unmatched rules to create custom rules.