vigiles 2.0.0

package/docs/spec-format.md

@@ -0,0 +1,194 @@
+# Spec Format Reference
+
+vigiles specs are TypeScript files (`*.spec.ts`) that compile to markdown instruction files. The spec is the source of truth; the markdown is a build artifact.
+
+## CLAUDE.md Specs
+
+Use `claude()` to define a CLAUDE.md spec. Export it as the default export.
+
+```ts
+import { claude, enforce, guidance, file, cmd, ref, instructions } from "vigiles";
+
+export default claude({
+  target: "CLAUDE.md",          // or "AGENTS.md", or ["CLAUDE.md", "AGENTS.md"]
+  sections: { ... },
+  keyFiles: { ... },
+  commands: { ... },
+  rules: { ... },
+  maxSectionLines: 30,          // optional: cap per-section line count
+});
+```
+
+### `target`
+
+`string | string[]` -- Output filename(s). Defaults to `"CLAUDE.md"`. Also used as the `# Heading` in compiled output. Pass an array to compile one spec to multiple targets:
+
+```ts
+target: ["CLAUDE.md", "AGENTS.md"],  // emits both from one spec
+```
+
+### `sections`
+
+`Record<string, string | InstructionFragment[]>` -- Named prose sections. Each key becomes a `## Heading` in the compiled output (first letter uppercased). Values are either plain strings or tagged templates via `instructions` with embedded `file()`, `cmd()`, and `ref()` references.
+
+```ts
+sections: {
+  architecture: `Two rule types: enforce() and guidance().`,
+  setup: instructions`See ${file("docs/setup.md")} and run ${cmd("npm install")}.`,
+}
+```
+
+### `keyFiles`
+
+`Record<string, string>` -- File paths mapped to descriptions. Each path is verified via `existsSync` at compile time. Compiles to a bullet list under `## Key Files`.
+
+```ts
+keyFiles: {
+  "src/spec.ts": "Type system and builder functions",
+  "src/compile.ts": "Compiler: spec to markdown with SHA-256 hash",
+}
+```
+
+### `commands`
+
+`Record<string, string>` -- Commands mapped to descriptions. `npm run <script>` and `npm <lifecycle>` commands are verified against `package.json` scripts at compile time. Compiles to a bullet list under `## Commands`.
+
+```ts
+commands: {
+  "npm run build": "Compile TypeScript to dist/",
+  "npm test": "Build and run all tests",
+}
+```
+
+### `rules`
+
+`Record<string, Rule>` -- Rule ID mapped to an `enforce()` or `guidance()` rule. The ID is kebab-cased by convention and is converted to a Title Case `### Heading` in compiled output. See [Rule Types](#rule-types) below.
+
+## SKILL.md Specs
+
+Use `skill()` to define a SKILL.md spec. Compiles to markdown with YAML frontmatter.
+
+```ts
+import { skill, file, cmd, ref, instructions } from "vigiles";
+
+export default skill({
+  name: "pr-to-lint-rule",
+  description: "Convert PR feedback into an automated lint rule",
+  argumentHint: "<description of recurring PR feedback>",
+  disableModelInvocation: true,
+  body: instructions`
+    Check ${file("eslint.config.ts")} for existing rules.
+    Run ${cmd("npm test")} to verify.
+    See ${ref("skills/other/SKILL.md")} for format.
+  `,
+});
+```
+
+| Field                    | Type                              | Required | Description                                         |
+| ------------------------ | --------------------------------- | -------- | --------------------------------------------------- |
+| `name`                   | `string`                          | yes      | Skill name (used in YAML frontmatter)               |
+| `description`            | `string`                          | yes      | Short description (frontmatter)                     |
+| `argumentHint`           | `string`                          | no       | Hint for the argument (frontmatter)                 |
+| `disableModelInvocation` | `boolean`                         | no       | Disable model invocation flag (frontmatter)         |
+| `body`                   | `string \| InstructionFragment[]` | yes      | Instruction body -- plain string or tagged template |
+
+## Reference Helpers
+
+Reference helpers create branded types that the compiler validates at compile time.
+
+### `file(path)`
+
+Returns a `FileRef` containing a `VerifiedPath`. The path is verified to exist via `existsSync` at compile time. Compiles to a backtick path in markdown: `` `path/to/file.ts` ``.
+
+### `cmd(command)`
+
+Returns a `CmdRef` containing a `VerifiedCmd`. For npm commands, the script is verified against `package.json` at compile time. Compiles to a backtick command: `` `npm run build` ``.
+
+### `ref(path)`
+
+Returns a `SkillRef` containing a `VerifiedRef`. The path is verified to exist at compile time. Compiles to a markdown link: `[dirname](path)`.
+
+### `instructions`
+
+Tagged template literal that interleaves strings and refs. Use it for `sections` values in `claude()` or the `body` of `skill()`.
+
+```ts
+instructions`Check ${file("tsconfig.json")} then run ${cmd("npm test")}.`;
+// Returns InstructionFragment[] -- the compiler renders and validates each ref.
+```
+
+## Rule Types
+
+### `enforce(linterRule, why)`
+
+Declares a rule delegated to an external linter. The `linterRule` accepts template literal types:
+
+- `${BuiltinLinter}/${string}` where BuiltinLinter is `eslint`, `stylelint`, `ruff`, `clippy`, `pylint`, or `rubocop`
+- `@${scope}/${rule}` for scoped ESLint plugins (e.g., `@typescript-eslint/no-explicit-any`)
+
+At compile time, vigiles verifies the rule exists in the linter's catalog and is enabled in the project's config. Compiles to `**Enforced by:** ` followed by the linter rule in backticks.
+
+```ts
+rules: {
+  "no-console-log": enforce("eslint/no-console", "Use structured logger."),
+  "no-print": enforce("ruff/T201", "Use logging module."),
+}
+```
+
+### `guidance(text)`
+
+Declares a prose-only rule with no mechanical enforcement. Guidance rules still participate in the monotonicity proof system: once a rule exists, it can be strengthened ( `guidance` → `enforce` ) but never weakened or removed without an explicit allowlist.
+
+```ts
+rules: {
+  "prefer-composition": guidance("Prefer composition over inheritance."),
+}
+```
+
+Compiles to: `**Guidance only** -- <text>`.
+
+## Branded Types
+
+`VerifiedPath`, `VerifiedCmd`, and `VerifiedRef` are branded string types (`string & { readonly [__brand]: "..." }`). They distinguish compiler-verified references from raw strings.
+
+- `file()` produces `FileRef` containing `VerifiedPath`
+- `cmd()` produces `CmdRef` containing `VerifiedCmd`
+- `ref()` produces `SkillRef` containing `VerifiedRef`
+
+The compiler only accepts these branded types in path-sensitive positions. This prevents passing unverified strings where a verified reference is expected -- the TypeScript compiler catches the error at authoring time.
+
+## Configuration
+
+Create `vigiles.config.ts` with `defineConfig()`:
+
+```ts
+import { defineConfig } from "vigiles";
+
+export default defineConfig({
+  specs: "**/*.spec.ts", // glob pattern for spec discovery (default: "**/*.spec.ts")
+  discover: true, // auto-discover linter rules for coverage reporting
+  maxRules: 50, // maximum rules per spec file
+  maxTokens: 2000, // maximum estimated tokens for compiled output (~4 chars/token)
+});
+```
+
+| Option      | Type      | Description                                             |
+| ----------- | --------- | ------------------------------------------------------- |
+| `specs`     | `string`  | Glob pattern to discover spec files                     |
+| `discover`  | `boolean` | Auto-discover linter rules for coverage reporting       |
+| `maxRules`  | `number`  | Compilation fails if a spec exceeds this rule count     |
+| `maxTokens` | `number`  | Compilation fails if estimated tokens exceed this limit |
+
+## Hash Verification
+
+Every compiled file starts with a SHA-256 integrity hash comment:
+
+```
+<!-- vigiles:sha256:a1b2c3d4e5f67890 compiled from CLAUDE.md.spec.ts -->
+```
+
+The hash covers the full compiled content (excluding the hash line itself), truncated to 16 hex characters.
+
+### `vigiles audit`
+
+Verifies that each compiled file's hash matches its content, reports linter rule coverage gaps, and suggests guidance rules that could be upgraded to `enforce()`. If someone manually edits the markdown, the hash will no longer match, and `vigiles audit` reports the file as modified. This ensures the spec remains the source of truth.

package/eslint.config.mjs

@@ -0,0 +1,79 @@
+import eslint from "@eslint/js";
+import tseslint from "@typescript-eslint/eslint-plugin";
+import tsparser from "@typescript-eslint/parser";
+import sonarjs from "eslint-plugin-sonarjs";
+import globals from "globals";
+
+export default [
+  {
+    ignores: ["dist/", "node_modules/"],
+  },
+  eslint.configs.recommended,
+  {
+    files: ["src/**/*.ts"],
+    languageOptions: {
+      parser: tsparser,
+      globals: {
+        ...globals.node,
+      },
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint,
+      sonarjs,
+    },
+    rules: {
+      ...tseslint.configs["strict-type-checked"]?.rules,
+      // TypeScript handles these better than ESLint
+      "no-undef": "off",
+      "no-unused-vars": "off",
+      // Allow unused vars prefixed with _
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+      ],
+      // We use createRequire legitimately for linter detection
+      "@typescript-eslint/no-require-imports": "off",
+      // Relax some strict rules that are too noisy for this codebase
+      "@typescript-eslint/restrict-template-expressions": "off",
+      "@typescript-eslint/no-unnecessary-condition": "off",
+      // Ban non-null assertions — use proper narrowing instead
+      "@typescript-eslint/no-non-null-assertion": "error",
+
+      // --- Complexity rules ---
+      complexity: ["warn", { max: 15 }],
+      "max-depth": ["warn", { max: 4 }],
+      "max-lines-per-function": [
+        "warn",
+        { max: 80, skipBlankLines: true, skipComments: true },
+      ],
+      "max-params": ["warn", { max: 4 }],
+
+      // --- SonarJS ---
+      "sonarjs/cognitive-complexity": ["warn", 15],
+      "sonarjs/no-duplicate-string": ["warn", { threshold: 4 }],
+      "sonarjs/no-identical-functions": "warn",
+      "sonarjs/no-duplicated-branches": "warn",
+      "sonarjs/no-identical-conditions": "error",
+      "sonarjs/no-identical-expressions": "error",
+      "sonarjs/no-nested-conditional": "warn",
+      "sonarjs/nested-control-flow": ["warn", { maximumNestingLevel: 3 }],
+    },
+  },
+  // Test files: relax promise, assertion, and complexity rules
+  {
+    files: ["src/**/*.test.ts"],
+    rules: {
+      // node:test describe/it return promises that don't need to be awaited
+      "@typescript-eslint/no-floating-promises": "off",
+      "@typescript-eslint/no-unnecessary-type-assertion": "off",
+      // Tests are naturally longer and more repetitive
+      "max-lines-per-function": "off",
+      "sonarjs/no-duplicate-string": "off",
+      "sonarjs/no-identical-functions": "off",
+    },
+  },
+];

package/examples/CLAUDE.md

@@ -0,0 +1,54 @@
+<!-- vigiles:sha256:f683550dbdfab721 compiled from examples/CLAUDE.md.spec.ts -->
+
+# CLAUDE.md
+
+## Positioning
+
+vigiles compiles `.spec.ts` files to instruction files (CLAUDE.md, AGENTS.md, or any markdown target). The spec is the source of truth. The markdown is a build artifact.
+
+The linter cross-referencing engine is the core moat: `enforce("@typescript-eslint/no-floating-promises")` verifies the rule exists AND is enabled in your linter config. Same for ESLint, Ruff, Clippy, Pylint, RuboCop, and Stylelint.
+
+`generate-types` is the second moat: scans all 6 linter APIs, package.json, and project files to emit a `.d.ts` with type unions. The TS compiler then PROVES references are valid at authoring time — typos become type errors, not runtime surprises.
+
+## Architecture
+
+Three rule types in specs: `enforce()` (delegated to external tool), `check()` (vigiles-owned filesystem assertion), `guidance()` (prose only).
+
+Core modules: `src/spec.ts` (types + builders), `src/compile.ts` (compiler), `src/linters.ts` (6-linter cross-referencing engine), `src/generate-types.ts` (type generator).
+
+## Key Files
+
+- `src/spec.ts` — Type system and builder functions
+- `src/compile.ts` — Compiler: spec → markdown with SHA-256 hash
+- `src/linters.ts` — Linter cross-referencing engine (6 linters)
+- `src/generate-types.ts` — Type generator: project state → .d.ts
+- `src/cli.ts` — CLI: compile, check, init, generate-types, discover, adopt
+
+## Commands
+
+- `npm run build` — Compile TypeScript to dist/
+- `npm test` — Build and run all tests
+- `npm run fmt` — Format with prettier
+- `npm run fmt:check` — Check formatting
+
+## Rules
+
+### Zero Config By Default
+
+**Guidance only** — vigiles compile should work with just a .spec.ts file. Config exists only for overrides (maxRules, maxTokens, catalogOnly).
+
+### Never Skip Tests
+
+**Guidance only** — All tests must pass. If a test requires a CLI tool (pylint, rubocop, ruff, clippy), install the tool, don't skip the test.
+
+### Dont Reimplement Linters
+
+**Guidance only** — Architectural linting belongs in ast-grep/Dependency Cruiser/Steiger. Per-file code rules belong in ESLint/Ruff/Clippy. vigiles owns: compilation, linter cross-referencing, type generation, filesystem assertions, and stale reference detection.
+
+### Format Before Commit
+
+**Guidance only** — Run `npm run fmt:check` before committing. Inline code spans in markdown need surrounding spaces to render correctly.
+
+### No Session Links
+
+**Guidance only** — This is a public repo. Claude Code session URLs are private and must not appear in commits or PRs.

package/examples/CLAUDE.md.spec.ts

@@ -0,0 +1,65 @@
+/**
+ * Example: CLAUDE.md specification for the vigiles project itself.
+ *
+ * This is the source of truth. CLAUDE.md is a compiled build artifact.
+ * Run `vigiles compile` to generate CLAUDE.md from this spec.
+ */
+import { claude, guidance } from "../src/spec.js";
+
+export default claude({
+  sections: {
+    positioning: `vigiles compiles \`.spec.ts\` files to instruction files (CLAUDE.md, AGENTS.md, or any markdown target). The spec is the source of truth. The markdown is a build artifact.
+
+The linter cross-referencing engine is the core moat: \`enforce("@typescript-eslint/no-floating-promises")\` verifies the rule exists AND is enabled in your linter config. Same for ESLint, Ruff, Clippy, Pylint, RuboCop, and Stylelint.
+
+\`generate-types\` is the second moat: scans all 6 linter APIs, package.json, and project files to emit a \`.d.ts\` with type unions. The TS compiler then PROVES references are valid at authoring time — typos become type errors, not runtime surprises.`,
+
+    architecture: `Three rule types in specs: \`enforce()\` (delegated to external tool), \`check()\` (vigiles-owned filesystem assertion), \`guidance()\` (prose only).
+
+Core modules: \`src/spec.ts\` (types + builders), \`src/compile.ts\` (compiler), \`src/linters.ts\` (6-linter cross-referencing engine), \`src/generate-types.ts\` (type generator).`,
+  },
+
+  keyFiles: {
+    "src/spec.ts": "Type system and builder functions",
+    "src/compile.ts": "Compiler: spec → markdown with SHA-256 hash",
+    "src/linters.ts": "Linter cross-referencing engine (6 linters)",
+    "src/generate-types.ts": "Type generator: project state → .d.ts",
+    "src/cli.ts": "CLI: compile, check, init, generate-types, discover, adopt",
+  },
+
+  commands: {
+    "npm run build": "Compile TypeScript to dist/",
+    "npm test": "Build and run all tests",
+    "npm run fmt": "Format with prettier",
+    "npm run fmt:check": "Check formatting",
+  },
+
+  rules: {
+    "zero-config-by-default": guidance(
+      "vigiles compile should work with just a .spec.ts file. Config exists only for overrides (maxRules, maxTokens, catalogOnly).",
+    ),
+
+    "never-skip-tests": guidance(
+      "All tests must pass. If a test requires a CLI tool (pylint, rubocop, ruff, clippy), install the tool, don't skip the test.",
+    ),
+
+    "dont-reimplement-linters": guidance(
+      "Architectural linting belongs in ast-grep/Dependency Cruiser/Steiger. Per-file code rules belong in ESLint/Ruff/Clippy. vigiles owns: compilation, linter cross-referencing, type generation, filesystem assertions, and stale reference detection.",
+    ),
+
+    "format-before-commit": guidance(
+      "Run `npm run fmt:check` before committing. Inline code spans in markdown need surrounding spaces to render correctly.",
+    ),
+
+    "no-session-links": guidance(
+      "This is a public repo. Claude Code session URLs are private and must not appear in commits or PRs.",
+    ),
+
+    // Example: check() rule (commented out because this is a demo spec,
+    // not the project's actual spec — see root CLAUDE.md.spec.ts)
+    // "test-file-pairing": check(
+    //   every("src/**/!(*test|*spec).ts").has("{name}.test.ts"),
+    //   "Every source module should have a corresponding test file.",
+    // ),
+  },
+});

package/examples/SKILL.md

@@ -0,0 +1,50 @@
+<!-- vigiles:sha256:da271d5e41e8e90e compiled from examples/SKILL.md.spec.ts -->
+
+---
+
+name: pr-to-lint-rule
+description: Convert a recurring PR review comment into an automated lint rule with tests and CLAUDE.md annotation
+disable-model-invocation: true
+argument-hint: <description of recurring PR feedback>
+
+---
+
+Convert a recurring PR review comment into an automated lint rule.
+
+## Arguments
+
+$ARGUMENTS — A natural language description of the pattern to enforce. Examples:
+
+- "we keep telling people not to import directly from antd, use our design system barrel file instead"
+- "people forget to use our custom logger instead of console.log"
+- "don't use unwrap() in production code, use expect() or proper error handling"
+- "API route handlers must use the withAuth wrapper"
+
+## Instructions
+
+You are generating an automated lint rule from a recurring code review pattern. Follow these steps:
+
+### Step 1: Detect the Project Language and Toolchain
+
+Look at the repository to determine:
+
+- **Primary language** (JS/TS, Python, Rust, Go, Ruby, etc.)
+- **Linter in use** (ESLint, Ruff, Clippy, golangci-lint, RuboCop, etc.)
+- **Testing framework** (Vitest, Jest, pytest, cargo test, etc.)
+- **Existing custom rules** (to match conventions)
+
+**If the language or linter cannot be confidently detected**, **ask the user** which language and linter to target before generating anything.
+
+### Step 2: Generate the Lint Rule
+
+Based on the detected (or user-specified) language, generate the appropriate rule type.
+
+For JavaScript/TypeScript, generate an ESLint rule using the AST visitor pattern with `meta` and `create(context)`.
+
+### Step 3: Update `CLAUDE.md`
+
+Add the annotation block. See [enforce-rules-format](skills/enforce-rules-format/SKILL.md) for the correct format.
+
+### Step 4: Verify
+
+Run `npm test` to ensure the new rule and tests pass.

package/examples/SKILL.md.spec.ts

@@ -0,0 +1,57 @@
+/**
+ * Example: SKILL.md specification for the pr-to-lint-rule skill.
+ *
+ * This is the source of truth. SKILL.md is a compiled build artifact.
+ * Run `vigiles compile` to generate SKILL.md from this spec.
+ */
+import { skill, file, cmd, ref, instructions } from "../src/spec.js";
+
+export default skill({
+  name: "pr-to-lint-rule",
+  description:
+    "Convert a recurring PR review comment into an automated lint rule with tests and CLAUDE.md annotation",
+  disableModelInvocation: true,
+  argumentHint: "<description of recurring PR feedback>",
+
+  body: instructions`
+Convert a recurring PR review comment into an automated lint rule.
+
+## Arguments
+
+$ARGUMENTS — A natural language description of the pattern to enforce. Examples:
+
+- "we keep telling people not to import directly from antd, use our design system barrel file instead"
+- "people forget to use our custom logger instead of console.log"
+- "don't use unwrap() in production code, use expect() or proper error handling"
+- "API route handlers must use the withAuth wrapper"
+
+## Instructions
+
+You are generating an automated lint rule from a recurring code review pattern. Follow these steps:
+
+### Step 1: Detect the Project Language and Toolchain
+
+Look at the repository to determine:
+
+- **Primary language** (JS/TS, Python, Rust, Go, Ruby, etc.)
+- **Linter in use** (ESLint, Ruff, Clippy, golangci-lint, RuboCop, etc.)
+- **Testing framework** (Vitest, Jest, pytest, cargo test, etc.)
+- **Existing custom rules** (to match conventions)
+
+**If the language or linter cannot be confidently detected**, **ask the user** which language and linter to target before generating anything.
+
+### Step 2: Generate the Lint Rule
+
+Based on the detected (or user-specified) language, generate the appropriate rule type.
+
+For JavaScript/TypeScript, generate an ESLint rule using the AST visitor pattern with \`meta\` and \`create(context)\`.
+
+### Step 3: Update ${file("CLAUDE.md")}
+
+Add the annotation block. See ${ref("skills/enforce-rules-format/SKILL.md")} for the correct format.
+
+### Step 4: Verify
+
+Run ${cmd("npm test")} to ensure the new rule and tests pass.
+`,
+});

package/fixtures/example-project/CLAUDE.md

@@ -0,0 +1,11 @@
+<!-- vigiles-disable require-spec -->
+
+# CLAUDE.md
+
+## Code Style
+
+Use TypeScript strict mode. Never use `any`.
+
+## Testing
+
+Run `npm test` before submitting. Every file in src/ should have tests.

package/fixtures/example-project/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "example-project",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "echo build",
+    "test": "echo test",
+    "lint": "echo lint"
+  }
+}

package/fixtures/example-project/src/index.ts

@@ -0,0 +1,3 @@
+export function greet(name: string): string {
+  return `Hello, ${name}!`;
+}

package/fixtures/example-project/src/utils.test.ts

@@ -0,0 +1,2 @@
+import { capitalize } from "./utils";
+console.assert(capitalize("hello") === "Hello");

package/fixtures/example-project/src/utils.ts

@@ -0,0 +1,3 @@
+export function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "vigiles",
+  "version": "2.0.0",
+  "description": "Compile .spec.ts files to instruction files (CLAUDE.md, AGENTS.md) with linter cross-referencing",
+  "bin": {
+    "vigiles": "dist/cli.js"
+  },
+  "main": "./dist/spec.js",
+  "types": "./dist/spec.d.ts",
+  "exports": {
+    ".": "./dist/spec.js",
+    "./spec": "./dist/spec.js",
+    "./compile": "./dist/compile.js",
+    "./linters": "./dist/linters.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test dist/spec.test.js dist/validate.test.js dist/cli.test.js dist/proofs.test.js dist/inline.test.js",
+    "lint": "eslint src/",
+    "fmt": "prettier --write .",
+    "fmt:check": "prettier --check ."
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/minimatch": "^5.1.2",
+    "@types/node": "^20.19.39",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "eslint": "^10.1.0",
+    "eslint-plugin-sonarjs": "^4.0.2",
+    "globals": "^17.4.0",
+    "prettier": "^3.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@jackchuka/mdschema": "^0.12.8",
+    "cosmiconfig": "^9.0.1",
+    "glob": "^13.0.6",
+    "minimatch": "^10.0.1"
+  }
+}