nostics 0.0.0 → 0.0.4

package/skills/nostics/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: nostics
+description: "Structured diagnostic code library for JavaScript/TypeScript. Turns errors, warnings, suggestions, and deprecations into typed, machine-readable Diagnostic objects with stable codes, docs URLs, and actionable fields. Use this skill whenever the project imports `@anthropic/nostics`, `nostics`, or works with `defineDiagnostics`, `createLogger`, `CodedError`, diagnostic code registries, structured error handling, or error code documentation pages. Also use when building custom formatters, reporters, or integrating diagnostic codes into a library or framework."
+---
+
+# nostics
+
+Structured diagnostic code library for JavaScript/TypeScript. Every error, warning, suggestion, and deprecation becomes a typed, serializable `Diagnostic` object with a stable code, docs URL, and actionable fields.
+
+## Core Concepts
+
+### Object-first design
+
+The fundamental unit is a plain `Diagnostic` object — serializable, transportable (client-server, worker-main, build tool-IDE). An `Error` class (`CodedError`) is only created at the moment `.throw()` is called.
+
+```ts
+interface Diagnostic {
+  code: string // e.g. 'NUXT_B2011'
+  level: 'error' | 'warn' | 'suggestion' | 'deprecation'
+  message: string // human-readable, already interpolated
+  why?: string // why this happened
+  fix?: string // how to resolve it
+  hint?: string // additional guidance
+  docs?: string // URL to documentation page for this code
+  sources?: SourceLocation[]
+  cause?: unknown
+  context?: Record<string, unknown>
+}
+```
+
+### Diagnostic levels
+
+- `error` — something is broken and must be fixed
+- `warn` — something may cause issues
+- `suggestion` — an improvement the user could make
+- `deprecation` — something that will be removed in a future version
+
+## API Reference
+
+### `defineDiagnostics(options)` — Define diagnostic codes
+
+Creates typed factory functions that produce plain `Diagnostic` objects. No side effects, no logging.
+
+```ts
+import { defineDiagnostics } from 'nostics'
+
+const diagnostics = defineDiagnostics({
+  docsBase: code => `https://nuxt.com/e/${code.replace('NUXT_', '').toLowerCase()}`,
+  codes: {
+    NUXT_B1001: {
+      message: 'Could not compile template.',
+      fix: 'Check the template for syntax errors.',
+    },
+    NUXT_B2011: {
+      message: (p: { src: string }) => `Invalid plugin \`${p.src}\`. src option is required.`,
+      fix: 'Pass a string path or an object with a `src` property to `addPlugin()`.',
+    },
+    NUXT_B5001: {
+      message: 'Missing compatibilityDate in nuxt.config.',
+      fix: (p: { date: string }) => `Add \`compatibilityDate: '${p.date}'\` to your nuxt.config.`,
+      hint: 'This ensures consistent behavior across Nuxt versions.',
+      level: 'warn',
+    },
+  },
+})
+```
+
+**Options:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `docsBase` | `string \| ((code: string) => string \| undefined)?` | Docs URL source. As a string, auto-generates `docs` as `${docsBase}/${code.toLowerCase()}`. As a function, receives the code key and returns the full URL (or `undefined` to omit). |
+| `codes` | `Record<string, DiagnosticDefinition>` | Map of code keys to their definitions |
+
+**DiagnosticDefinition fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `message` | `string \| (params) => string` | Required. The diagnostic message |
+| `fix` | `string \| (params) => string` | Optional. How to resolve the issue |
+| `why` | `string \| (params) => string` | Optional. Why this diagnostic was triggered |
+| `hint` | `string \| (params) => string` | Optional. Additional contextual guidance |
+| `level` | `DiagnosticLevel` | Optional. Defaults to `'error'` |
+
+**Type inference:** Parameters are extracted from ALL template fields (`message`, `fix`, `why`, `hint`) and intersected. If `message` needs `{ src }` and `fix` needs `{ date }`, the factory requires `{ src, date }`.
+
+**Factory usage:**
+
+```ts
+// No params — factory takes optional overrides only
+diagnostics.NUXT_B1001()
+diagnostics.NUXT_B1001({ level: 'warn' })
+
+// With params — first arg is params, second is optional overrides
+diagnostics.NUXT_B2011({ src: '/plugins/bad.ts' })
+diagnostics.NUXT_B2011({ src: '/plugins/bad.ts' }, { cause: originalError })
+```
+
+**Registry methods** (non-enumerable on the result):
+
+```ts
+diagnostics.codes() // → ['NUXT_B1001', 'NUXT_B2011', 'NUXT_B5001']
+diagnostics.has('NUXT_B1001') // → true (type guard: narrows to known code key)
+diagnostics.get('NUXT_B1001') // → the raw DiagnosticDefinition
+diagnostics.extend({ // → new diagnostics set with additional codes merged in
+  NUXT_B9999: { message: 'New code.' }
+})
+```
+
+### `createLogger(options)` — Bind diagnostics to output
+
+Merges diagnostic sets and wraps each code factory to return `DiagnosticActions` — a `Diagnostic` enriched with action methods.
+
+```ts
+import { consoleReporter, createLogger, plainFormatter } from 'nostics'
+import { ansiFormatter } from 'nostics/formatters/ansi'
+
+const log = createLogger({
+  diagnostics: [diagnostics],
+  formatter: ansiFormatter(colors), // or plainFormatter (default)
+  reporter: consoleReporter, // default — pass a single function or an array
+})
+```
+
+**Usage:**
+
+```ts
+log.NUXT_B2011({ src: pluginPath }).throw() // formats, reports, then throws CodedError
+log.NUXT_B1001().warn() // overrides level to 'warn', formats, reports
+log.NUXT_B5001({ date: '2025-01-01' }).log() // uses the definition's level ('warn')
+log.NUXT_B1001().format() // returns the formatted string only
+
+// Raw methods for pre-built Diagnostic objects
+log.throw(diagnostics.NUXT_B2011({ src: pluginPath }))
+log.warn(diagnostics.NUXT_B1001())
+```
+
+**Multiple diagnostic sets:**
+
+```ts
+const log = createLogger({
+  diagnostics: [nuxtDiagnostics, i18nDiagnostics],
+})
+
+log.NUXT_B2011({ src: pluginPath }).throw() // [NUXT_B2011] ...
+log.I18N_I001({ locale: 'fr' }).warn() // [I18N_I001] ...
+```
+
+### `CodedError` — Error class
+
+Created only when `.throw()` is called. Extends `Error` with `name: 'CodedError'`.
+
+```ts
+class CodedError extends Error {
+  readonly diagnostic: Diagnostic // the full object
+}
+```
+
+The `message` is formatted as `[CODE] message text`. Access all diagnostic fields via `err.diagnostic`.
+
+**Catch and inspect:**
+
+```ts
+try {
+  log.NUXT_B2011({ src: pluginPath }).throw()
+}
+catch (err) {
+  if (err instanceof CodedError) {
+    console.log(err.diagnostic.code) // 'NUXT_B2011'
+    console.log(err.diagnostic.docs) // 'https://nuxt.com/e/b2011'
+    console.log(err.diagnostic.fix) // 'Pass a string path...'
+  }
+}
+```
+
+### Formatters
+
+All are plain functions: `(d: Diagnostic) => string`.
+
+| Formatter | Import | Description |
+|-----------|--------|-------------|
+| `plainFormatter` | `nostics` | Unicode box-drawing, no colors. Default. |
+| `ansiFormatter(colors)` | `nostics/formatters/ansi` | Accepts a generic `Colors` interface — no hard ANSI dependency |
+| `jsonFormatter` | `nostics/formatters/json` | `JSON.stringify(diagnostic)` |
+
+**ANSI formatter `Colors` interface:**
+
+```ts
+interface Colors {
+  red: (s: string) => string
+  yellow: (s: string) => string
+  cyan: (s: string) => string
+  gray: (s: string) => string
+  bold: (s: string) => string
+  dim: (s: string) => string
+}
+```
+
+**Plain formatter output:**
+
+```
+[NUXT_B2011] Invalid plugin `/plugins/bad.ts`. src option is required.
+├▶ why: The plugin object was passed without a src path
+├▶ fix: Pass a string path or an object with a `src` property to `addPlugin()`.
+├▶ hint: Check your module's addPlugin() calls
+╰▶ see: https://nuxt.com/e/b2011
+```
+
+Detail line order is fixed: `why` → `fix` → `hint` → `see` (docs URL). Missing fields are omitted.
+
+**Writing a custom formatter:**
+
+```ts
+import type { Formatter } from 'nostics'
+
+const myFormatter: Formatter = (d) => {
+  return `[${d.code}] ${d.message}${d.fix ? ` (fix: ${d.fix})` : ''}`
+}
+```
+
+### Formatting utilities
+
+Two lower-level functions are exported for building custom formatters:
+
+- `formatTag(d: Diagnostic)` — returns the `[CODE]` tag string (e.g. `[NUXT_B2011]` for code `'NUXT_B2011'`)
+- `renderFrame(d: Diagnostic)` — returns the full box-drawing formatted string (same as `plainFormatter`)
+
+### Reporters
+
+All are plain functions: `(d: Diagnostic, formatted: string) => void`. Pass a single reporter or an array.
+
+| Reporter | Import | Description |
+|----------|--------|-------------|
+| `consoleReporter` | `nostics` | `console.error` for `'error'` level, `console.warn` for all others |
+| `createFetchReporter(url)` | `nostics` | POSTs diagnostic JSON to the given URL (silently ignores fetch errors) |
+
+**Writing a custom reporter:**
+
+```ts
+import type { Reporter } from 'nostics'
+
+const fileReporter: Reporter = (diagnostic, formatted) => {
+  fs.appendFileSync('errors.log', `${formatted}\n`)
+}
+```
+
+### Overrides
+
+When calling a factory, you can pass `Overrides` to attach runtime context:
+
+```ts
+type Overrides = Partial<Pick<Diagnostic, 'level' | 'sources' | 'cause' | 'context'>>
+```
+
+```ts
+diagnostics.NUXT_B2011({ src: pluginPath }, {
+  cause: originalError,
+  sources: [{ file: 'nuxt.config.ts', line: 42 }],
+  context: { moduleName: 'my-module' },
+})
+```
+
+## Best Practices
+
+### Code naming conventions
+
+- Use fully qualified, stable code identifiers (e.g. `NUXT_B1001`, `I18N_I001`)
+- Group by domain using a letter prefix within the code: `B` for build, `R` for runtime, `C` for config, etc.
+- Never reuse or reassign a code once published — codes are permanent identifiers
+
+### Structuring diagnostic definitions
+
+- Always provide `message` — it is the only required field
+- Provide `fix` whenever the solution is known — this is the most actionable field for both humans and AI agents
+- Provide `why` to explain root causes when the reason may not be obvious from the message alone
+- Use `hint` for supplementary guidance that doesn't fit in `fix` (e.g. links to related docs, edge cases)
+- Set the appropriate `level` — default is `'error'`, override to `'warn'`, `'suggestion'`, or `'deprecation'` as needed
+- Use parameterized templates for messages that include runtime values — avoid string concatenation outside the factory
+
+### Organizing diagnostic files
+
+For large projects, split diagnostics by domain:
+
+```
+src/
+  diagnostics/
+    build.ts       # NUXT_B-series codes
+    runtime.ts     # NUXT_R-series codes
+    config.ts      # NUXT_C-series codes
+    index.ts       # re-exports and merges all sets
+```
+
+Each file calls `defineDiagnostics()` with the same `docsBase` but different code ranges.
+
+## Documentation Site
+
+For guidance on building error code documentation pages (structure, templates, deployment, and AI-agent optimization), read `references/documentation-site.md`.

package/skills/nostics/references/documentation-site.md

@@ -0,0 +1,203 @@
+# Documentation Site and Error Code Registry
+
+## Table of Contents
+
+- [Why a documentation site matters](#why-a-documentation-site-matters)
+- [Setting up docsBase](#setting-up-docsbase)
+- [Documentation page structure](#documentation-page-structure)
+- [Page template](#page-template)
+- [Deployment recommendations](#deployment-recommendations)
+- [Keeping docs in sync with code](#keeping-docs-in-sync-with-code)
+- [Optimizing for AI agent consumption](#optimizing-for-ai-agent-consumption)
+
+## Why a documentation site matters
+
+Every diagnostic code should have a dedicated, publicly accessible documentation page. This serves three audiences:
+
+1. **Developers** encountering the error in their terminal or logs can click the `see:` URL and get immediate guidance
+2. **AI agents** (Claude, Copilot, etc.) can fetch the page content to provide contextual help when a user pastes an error
+3. **Search engines** index these pages so developers searching for `NUXT_B2011` find the answer directly
+
+## Setting up docsBase
+
+The `docsBase` option in `defineDiagnostics()` controls the auto-generated `docs` URL. It can be a string or a function:
+
+```ts
+// Function form — full control over the URL
+const diagnostics = defineDiagnostics({
+  docsBase: code => `https://nuxt.com/e/${code.replace('NUXT_', '').toLowerCase()}`,
+  codes: {
+    NUXT_B2011: { message: '...' },
+  },
+})
+// diagnostics.NUXT_B2011().docs → 'https://nuxt.com/e/b2011'
+```
+
+```ts
+// String form — code appended automatically as ${docsBase}/${code.toLowerCase()}
+const diagnostics = defineDiagnostics({
+  docsBase: 'https://example.com/errors',
+  codes: {
+    MY_E001: { message: '...' },
+  },
+})
+// diagnostics.MY_E001().docs → 'https://example.com/errors/my_e001'
+```
+
+Plan your URL structure accordingly.
+
+## Documentation page structure
+
+Each error code page (e.g. `https://nuxt.com/e/b2011`) should follow this structure. The content must be both human-readable and optimized for AI agent consumption — use clear headings, concise language, and structured sections.
+
+### Required sections
+
+**Title and code identifier**
+
+```markdown
+# NUXT_B2011: Invalid plugin — src option is required
+
+Code: `NUXT_B2011`
+Level: error
+```
+
+Start with the code and a short human-readable title. Include the code and the severity level.
+
+**What this error means**
+
+```markdown
+## What this error means
+
+This error occurs when a plugin is registered via `addPlugin()` without providing a
+valid `src` path. Nuxt requires every plugin to have a source file so it can be
+resolved and included in the build.
+```
+
+Explain the error in plain language. Assume the reader has no prior context — describe what the system expected vs what it received. This section is the primary content AI agents will use to explain the error to users.
+
+**Why this happens**
+
+```markdown
+## Why this happens
+
+Common causes:
+
+- Passing an object to `addPlugin()` without a `src` property
+- Passing `undefined` or `null` as the plugin path
+- A module is constructing a plugin object dynamically and the `src` field is missing
+  due to a conditional branch or typo
+```
+
+List the concrete scenarios that trigger this diagnostic. Use bullet points. Each bullet should be a specific, recognizable situation the developer might be in.
+
+**How to fix it**
+
+```markdown
+## How to fix it
+
+Ensure every call to `addPlugin()` includes a valid `src` path:
+
+\```ts
+// Wrong
+addPlugin({ name: 'my-plugin' })
+
+// Correct
+addPlugin({ src: resolve('./runtime/my-plugin'), name: 'my-plugin' })
+
+// Also correct — pass a string directly
+addPlugin(resolve('./runtime/my-plugin'))
+\```
+
+If the plugin path is computed dynamically, verify the variable is defined before
+passing it to `addPlugin()`.
+```
+
+Provide concrete code examples showing the wrong pattern and the corrected version. This is the most important section — it should be copy-pasteable.
+
+### Optional sections
+
+**Additional context**
+
+```markdown
+## Additional context
+
+- This validation was added in Nuxt 3.2
+- If you are writing a Nuxt module, see the [Module Author Guide](https://nuxt.com/docs/guide/going-further/modules)
+- Related codes: [NUXT_B1001](./nuxt_b1001) (template compilation), [NUXT_B3005](./nuxt_b3005) (module resolution)
+```
+
+Link to related documentation, changelog entries, or related diagnostic codes.
+
+**Example diagnostic output**
+
+```markdown
+## Example output
+
+\```
+[NUXT_B2011] Invalid plugin `/plugins/bad.ts`. src option is required.
+├▶ why: The plugin object was passed without a src path
+├▶ fix: Pass a string path or an object with a `src` property to `addPlugin()`.
+├▶ hint: Check your module's addPlugin() calls
+╰▶ see: https://nuxt.com/e/b2011
+\```
+```
+
+Show what the user actually sees in their terminal so they can confirm they're on the right page.
+
+## Page template
+
+Use this template for each error code page:
+
+```markdown
+# {CODE}: {Short title}
+
+Code: `{CODE}`
+Level: {error|warn|suggestion|deprecation}
+
+## What this error means
+
+{Plain-language explanation of the diagnostic. 1-3 sentences.}
+
+## Why this happens
+
+{Bulleted list of concrete scenarios that trigger this diagnostic.}
+
+## How to fix it
+
+{Code examples showing the wrong pattern and the corrected version.}
+
+## Additional context
+
+{Links to related docs, changelog, or related diagnostic codes. Optional.}
+
+## Example output
+
+{Terminal output showing the formatted diagnostic. Optional.}
+```
+
+## Deployment recommendations
+
+Host the error code pages on a public URL that matches your `docsBase`:
+
+- **GitHub Pages or static site generator** (VitePress, Nuxt Content, etc.) — create a directory of markdown files, one per code, with a catch-all route at `/e/[code].md`
+- **Dedicated `/errors` or `/e` route** in your existing documentation site
+- Ensure pages return proper HTTP status codes (200 for valid codes, 404 for unknown codes) so agents and crawlers can distinguish valid codes from missing ones
+- Use `<meta>` tags or frontmatter for structured data (code, level, title) to improve agent and search engine consumption
+- Keep pages lightweight — avoid heavy JavaScript or SPAs that block content rendering for fetch-based agents
+
+## Keeping docs in sync with code
+
+- Store documentation markdown alongside your diagnostic definitions or in a dedicated `docs/errors/` directory
+- Generate an index page listing all codes with their messages and levels
+- In CI, validate that every code in `defineDiagnostics()` has a corresponding documentation page — fail the build if a page is missing
+- When adding a new diagnostic code, add the documentation page in the same PR
+
+## Optimizing for AI agent consumption
+
+Pages should be structured so that an AI agent fetching the URL can extract the relevant information without ambiguity:
+
+- Use consistent heading hierarchy (`##` for sections)
+- Put the most actionable content (fix instructions) early
+- Avoid hiding critical information in collapsed sections, tabs, or JavaScript-rendered content
+- Include the code in the page title and body so keyword matching works
+- Keep code examples self-contained — an agent should be able to suggest the fix from the page content alone

package/index.js

@@ -1 +0,0 @@
-// Placeholder