@skillit/core 1.5.0 → 2.0.0

package/dist/refine/ast-edit.js

@@ -1,5 +1,6 @@
 // packages/core/src/refine/ast-edit.ts
 import { parse, Lang } from '@ast-grep/napi';
+import { escapeJsDocClose, findPropertyByPath, findTypeBody, unescapeJsDocClose } from '../config-extract.js';
 // `satisfies` ensures every listed value is a valid RefineTag. The
 // `MissingTags` assertion below makes the inverse hold too: if a value is added
 // to the RefineTag union but not to this list, compilation fails — so the
@@ -90,34 +91,179 @@ function leadingJsDoc(anchorNode) {
  * - If a JSDoc block exists without the tag, the tag is appended before the
  *   closing `*\/`.
  * - If the declaration is not found, the source is returned unchanged.
+ *
+ * @remarks
+ * Parses `source` with ast-grep (core carries no `typescript` dependency) and
+ * edits the text in place, so formatting outside the touched JSDoc block is
+ * preserved. Tag matching is by name, so re-running with the same tag is a
+ * no-op rather than a duplicate.
  */
 export function upsertJsDocTag(source, declName, tag, content) {
     const root = parse(Lang.TypeScript, source).root();
     const anchorNode = findDeclaration(root, declName);
     if (!anchorNode)
         return source;
-    const tagText = `@${tag} ${content}`;
+    return upsertTagOnAnchor(source, root, anchorNode, tag, content);
+}
+/**
+ * Insert or update a JSDoc tag on a property of a config type.
+ *
+ * `propertyPath` is a dot path into the interface or object-type alias named
+ * `typeName` (e.g. `outDir` or `components.prefix`). Otherwise behaves like
+ * {@link upsertJsDocTag}. Returns the source unchanged when the type or
+ * property is not found. Used by the config refine source to write routing
+ * tags back onto a config type's property declarations.
+ *
+ * @remarks
+ * Resolves `propertyPath` against the body of `typeName` via ast-grep, recursing
+ * into nested object-type members for dotted paths. Like {@link upsertJsDocTag},
+ * the edit is text-level and idempotent per tag name.
+ */
+export function upsertPropertyJsDocTag(source, typeName, propertyPath, tag, content) {
+    const root = parse(Lang.TypeScript, source).root();
+    const body = findTypeBody(root, typeName);
+    if (!body)
+        return source;
+    const property = findPropertyByPath(body, propertyPath);
+    if (!property)
+        return source;
+    return upsertTagOnAnchor(source, root, property, tag, content);
+}
+/**
+ * Insert or update `@tag content` on the JSDoc block leading `anchorNode`,
+ * creating the block when absent. Idempotent per tag (matches the tag NAME, so
+ * multi-line content never produces duplicates) and rebuilds the block as
+ * well-formed multi-line (handling single-line `/** text *\/` inputs). Shared by
+ * the declaration-level ({@link upsertJsDocTag}) and property-level
+ * ({@link upsertPropertyJsDocTag}) upserts.
+ */
+function upsertTagOnAnchor(source, root, anchorNode, tag, content) {
+    // Escape any comment-close sequence in the content so a value containing it
+    // (e.g. a glob like `**/*.ts` in a config pitfall) can't terminate the block
+    // early and corrupt the file. readJsDocTags / config extraction unescape it.
+    const tagText = escapeJsDocClose(`@${tag} ${content}`);
     const jsdocNode = leadingJsDoc(anchorNode);
+    // Indent from the comment when one exists: it may sit on the SAME line as the
+    // declaration (`/** x */ prop`), where the declaration's own column is the
+    // text after the comment, not the line indent — using it over-indented every
+    // rebuilt continuation line. With no comment, indent from the declaration the
+    // new block is prepended to.
+    const indent = ' '.repeat((jsdocNode ?? anchorNode).range().start.column);
     if (jsdocNode) {
         const block = jsdocNode.text();
-        if (block.includes(tagText))
+        if (block.match(new RegExp(`(^|\\n)\\s*\\*?\\s*@${tag}\\b`)))
             return source;
-        // Determine the indent of the closing */ line
-        const closeOffset = block.lastIndexOf('*/');
-        const beforeClose = block.slice(0, closeOffset);
-        // The whitespace prefix of the closing `*/` line
-        const linePrefix = beforeClose.match(/([^\n]*)$/)?.[1] ?? ' ';
-        const merged = block.slice(0, closeOffset - linePrefix.length) +
-            `${linePrefix}* ${tagText}\n${linePrefix}*/`;
-        return root.commitEdits([jsdocNode.replace(merged)]);
+        const innerLines = block
+            .replace(/^\/\*\*/, '')
+            .replace(/\s*\*\/\s*$/, '')
+            .split('\n')
+            .map((line) => line.replace(/^\s*\*? ?/, '').trimEnd());
+        while (innerLines.length > 0 && innerLines[0] === '')
+            innerLines.shift();
+        while (innerLines.length > 0 && innerLines[innerLines.length - 1] === '')
+            innerLines.pop();
+        // Prefix every physical line (including multi-line tag content) with ` * `.
+        const allLines = [...innerLines, ...tagText.split('\n')];
+        const body = allLines
+            .map((line) => (line.length > 0 ? `${indent} * ${line}` : `${indent} *`))
+            .join('\n');
+        const merged = `/**\n${body}\n${indent} */`;
+        // Own-line comment: a clean node replace suffices.
+        if (jsdocNode.range().end.line !== anchorNode.range().start.line) {
+            return root.commitEdits([jsdocNode.replace(merged)]);
+        }
+        // Same-line `/** x */ prop`: a node replace swaps only the comment text and
+        // leaves the declaration packed onto the closing `*/` line. Splice manually
+        // — drop the inline gap and start the declaration on its own indented line.
+        const start = jsdocNode.range().start.index;
+        const end = jsdocNode.range().end.index;
+        const tail = source.slice(end).replace(/^[^\S\n]+/, '');
+        return `${source.slice(0, start)}${merged}\n${indent}${tail}`;
     }
-    // No existing JSDoc — create one before the anchor node.
-    const col = anchorNode.range().start.column;
-    const indent = ' '.repeat(col);
+    // No existing JSDoc — create one before the anchor node. Prefix EVERY physical
+    // line of the tag (multi-line content too) with ` * `, mirroring the merge
+    // branch above. Without this, a multi-line first tag left continuation lines
+    // at column 0 — malformed JSDoc that also broke the re-parse for any tag
+    // appended to the same declaration in a later pass.
     const at = anchorNode.range().start.index;
-    const blockText = `/**\n${indent} * ${tagText}\n${indent} */\n${indent}`;
+    const body = tagText
+        .split('\n')
+        .map((line) => (line.length > 0 ? `${indent} * ${line}` : `${indent} *`))
+        .join('\n');
+    const blockText = `/**\n${body}\n${indent} */\n${indent}`;
     return source.slice(0, at) + blockText + source.slice(at);
 }
+// Fast membership set for tag-name lookups (typed as strings so an arbitrary
+// captured `@word` can be tested without a cast). Derived from REFINE_TAGS so
+// it stays in sync with the union automatically.
+const REFINE_TAG_SET = new Set(REFINE_TAGS);
+/**
+ * Remove the refine-managed tag spans (`@useWhen`, `@avoidWhen`, `@pitfalls`,
+ * `@remarks`, `@example` — see {@link REFINE_TAGS}) from every JSDoc block in
+ * `source`, leaving each block's prose description and any non-refine tags
+ * intact.
+ *
+ * Used to feed an annotated config module back to the model as grounding
+ * without echoing the routing tags this package itself wrote across earlier
+ * refine iterations — those are documentation, not the implementation the model
+ * should ground runtime claims in. Unlike a blanket JSDoc strip, this preserves
+ * genuine hand-authored docs (e.g. validation notes on a `defineConfig` helper),
+ * which are exactly the runtime-behavior grounding we want to keep.
+ *
+ * Handles single-line (`/** @tag x *​/`) as well as multi-line blocks: each block
+ * is reduced to its inner content (opener/closer and ` * ` gutter dropped) before
+ * tags are matched, so an inline opener can't hide a tag. The block-matching
+ * regex is non-greedy, and writeback escapes a literal close sequence in content
+ * to `*\/`, so an escaped sequence inside a kept line never terminates early.
+ */
+export function stripRefineTags(source) {
+    return source.replace(/\/\*\*[\s\S]*?\*\//g, (block, offset) => {
+        // Indent of the line the block opens on, for a clean re-wrap when we rebuild.
+        const lineStart = source.lastIndexOf('\n', offset) + 1;
+        const indent = source.slice(lineStart, offset).match(/^\s*/)?.[0] ?? '';
+        return stripRefineTagsFromBlock(block, indent);
+    });
+}
+/**
+ * Strip refine-tag spans from one JSDoc block. Returns the block unchanged when
+ * it holds no refine tag (preserving hand-authored formatting), the empty string
+ * when nothing but refine tags remain (the whole block is dropped), or a clean
+ * re-wrapped block at `indent` otherwise. A `@tag` line and the lines following
+ * it (its continuation) form one span; a non-refine `@tag` closes any open span.
+ */
+function stripRefineTagsFromBlock(block, indent) {
+    // Reduce to inner content so tag detection is independent of how the block is
+    // wrapped: drop the `/**` opener and `*/` closer (own-line OR inline, as in a
+    // single-line `/** @tag x */`), then the per-line ` * ` gutter.
+    const inner = block.replace(/^\s*\/\*\*/, '').replace(/\*\/\s*$/, '');
+    const lines = inner.split('\n').map((line) => line.replace(/^\s*\*? ?/, '').trimEnd());
+    const kept = [];
+    let dropping = false;
+    let droppedAny = false;
+    for (const line of lines) {
+        const tagMatch = line.match(/^@(\w+)\b/);
+        if (tagMatch) {
+            dropping = REFINE_TAG_SET.has(tagMatch[1] ?? '');
+        }
+        if (dropping) {
+            droppedAny = true;
+            continue;
+        }
+        kept.push(line);
+    }
+    if (!droppedAny)
+        return block; // no refine tag — keep original formatting verbatim
+    while (kept.length > 0 && kept[0] === '')
+        kept.shift();
+    while (kept.length > 0 && kept[kept.length - 1] === '')
+        kept.pop();
+    if (kept.length === 0)
+        return ''; // block was nothing but refine tags
+    const body = kept
+        .map((line) => (line.length > 0 ? `${indent} * ${line}` : `${indent} *`))
+        .join('\n');
+    return `/**\n${body}\n${indent} */`;
+}
 /**
  * Parse the leading JSDoc block of a named export declaration and return a
  * map of the RefineTag values found in it.
@@ -134,13 +280,35 @@ export function readJsDocTags(source, declName) {
     if (!jsdocNode)
         return {};
     const block = jsdocNode.text();
+    // Strip the block to inner content lines (no `/** */` wrapper, no ` * `
+    // prefixes), then walk them: a known `@tag` line opens a capture and the
+    // following non-tag lines are its continuation. This keeps multi-line tag
+    // content (e.g. bullet lists) intact instead of truncating at the first
+    // newline — otherwise a refined `@pitfalls` with several bullets would lose
+    // everything past line one when re-extracted into SKILL.md.
+    const innerLines = block
+        .replace(/^\/\*\*/, '')
+        .replace(/\s*\*\/\s*$/, '')
+        .split('\n')
+        .map((line) => line.replace(/^\s*\*? ?/, '').trimEnd());
+    const collected = {};
+    let current;
+    for (const line of innerLines) {
+        const tagMatch = line.match(/^@(\w+)\s?(.*)$/);
+        const matchedTag = tagMatch ? REFINE_TAGS.find((t) => t === tagMatch[1]) : undefined;
+        if (matchedTag) {
+            current = matchedTag;
+            collected[current] = [tagMatch[2] ?? ''];
+        }
+        else if (current) {
+            collected[current].push(line);
+        }
+    }
     const result = {};
     for (const tag of REFINE_TAGS) {
-        const pattern = new RegExp(`@${tag}\\s+(.+?)(?:\\s*\\n|\\s*\\*\\/|$)`, 'm');
-        const hit = block.match(pattern);
-        if (hit) {
-            result[tag] = hit[1]?.trim() ?? '';
-        }
+        const lines = collected[tag];
+        if (lines)
+            result[tag] = unescapeJsDocClose(lines.join('\n').trim());
     }
     return result;
 }

package/dist/refine/ast-edit.js.map

@@ -1 +1 @@
-{"version":3,"file":"ast-edit.js","sourceRoot":"","sources":["../../src/refine/ast-edit.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAI7C,mEAAmE;AACnE,gFAAgF;AAChF,0EAA0E;AAC1E,qEAAqE;AACrE,MAAM,WAAW,GAAG;IAClB,SAAS;IACT,WAAW;IACX,UAAU;IACV,SAAS;IACT,SAAS;CAC8B,CAAC;AAK1C,MAAM,WAAW,GAAU,SAAwB,CAAC;AACpD,KAAK,WAAW,CAAC;AAEjB;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,IAAY,EAAE,QAAgB;IACxD,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IACtB,IACE,CAAC,KAAK,sBAAsB;QAC5B,CAAC,KAAK,mBAAmB;QACzB,CAAC,KAAK,4BAA4B;QAClC,CAAC,KAAK,uBAAuB;QAC7B,CAAC,KAAK,kBAAkB;QACxB,CAAC,KAAK,wBAAwB,EAC9B,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACpC,OAAO,QAAQ,EAAE,IAAI,EAAE,KAAK,QAAQ,CAAC;IACvC,CAAC;IACD,IAAI,CAAC,KAAK,qBAAqB,IAAI,CAAC,KAAK,sBAAsB,EAAE,CAAC;QAChE,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;YACzC,IAAI,UAAU,CAAC,IAAI,EAAE,KAAK,qBAAqB;gBAAE,SAAS;YAC1D,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC1C,IAAI,QAAQ,EAAE,IAAI,EAAE,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,eAAe,CAAC,IAAY,EAAE,QAAgB;IACrD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;QACpC,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,kBAAkB,EAAE,CAAC;YACxC,oEAAoE;YACpE,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;gBACrC,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,QAAQ;oBAAE,SAAS,CAAC,gBAAgB;gBACzD,IAAI,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC;oBAAE,OAAO,KAAK,CAAC;YACxD,CAAC;YACD,SAAS;QACX,CAAC;QACD,6CAA6C;QAC7C,IAAI,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;IACxD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,UAAkB;IACtC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAc,EACd,QAAgB,EAChB,GAAc,EACd,OAAe;IAEf,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IACnD,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACnD,IAAI,CAAC,UAAU;QAAE,OAAO,MAAM,CAAC;IAE/B,MAAM,OAAO,GAAG,IAAI,GAAG,IAAI,OAAO,EAAE,CAAC;IACrC,MAAM,SAAS,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IAE3C,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,OAAO,MAAM,CAAC;QAE3C,8CAA8C;QAC9C,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC5C,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;QAChD,iDAAiD;QACjD,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;QAE9D,MAAM,MAAM,GACV,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC;YAC/C,GAAG,UAAU,KAAK,OAAO,KAAK,UAAU,IAAI,CAAC;QAE/C,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,yDAAyD;IACzD,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;IAC5C,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,EAAE,GAAG,UAAU,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC;IAC1C,MAAM,SAAS,GAAG,QAAQ,MAAM,MAAM,OAAO,KAAK,MAAM,QAAQ,MAAM,EAAE,CAAC;IACzE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAc,EACd,QAAgB;IAEhB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IACnD,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACnD,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,CAAC;IAE3B,MAAM,SAAS,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IAC3C,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,CAAC;IAE1B,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAuC,EAAE,CAAC;IAEtD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,IAAI,GAAG,mCAAmC,EAAE,GAAG,CAAC,CAAC;QAC5E,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,GAAG,EAAE,CAAC;YACR,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACrC,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"ast-edit.js","sourceRoot":"","sources":["../../src/refine/ast-edit.ts"],"names":[],"mappings":"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"}

package/dist/refine/config-source.d.ts

@@ -0,0 +1,81 @@
+import type { ExtractedSkill } from '../types.js';
+import type { DraftedFix, RefineSource, TargetLocation } from './types.js';
+export interface ConfigRefineSourceOptions {
+    /** Path to the TypeScript file declaring the config type. */
+    configFile: string;
+    /** Name of the exported interface or object-type alias to document. */
+    typeName: string;
+    /** Skill name (defaults to the package name, then `typeName`). */
+    name?: string;
+    /** Skill description (defaults to the package.json description). */
+    description?: string;
+    /**
+     * Globs pointing at the code that CONSUMES this config (e.g. the CLI/filter
+     * logic). Their contents are fed to the draft model as an implementation
+     * reference so it can state CORRECT runtime behavior instead of guessing it
+     * from the type alone. Token-capped. Without grounding the model is told not
+     * to assert unverifiable runtime semantics.
+     */
+    groundingGlobs?: string[];
+}
+/**
+ * {@link RefineSource} for a TypeScript configuration surface.
+ *
+ * Reads the consumer's config type with {@link extractConfigSurface}, exposes it
+ * as a single `config` surface in an {@link ExtractedSkill}, and writes routing
+ * tags back as JSDoc onto the type's individual property declarations. Unlike
+ * the CLI source — whose routing lives at the command (surface) level — a config
+ * surface is documented per-OPTION: each fix targets one property by its
+ * dot-path `configKey` (e.g. `outDir`, `components.prefix`), routed through
+ * {@link upsertPropertyJsDocTag}.
+ *
+ * It also enriches the skill from the package.json nearest the config file (its
+ * description, keywords, repository) and a sibling README, supplying the audit
+ * context the metadata checks (F1/F2/F3/E5/W4/W5/W6) score against — without it
+ * a config skill forfeits those points even when the package already carries
+ * the data.
+ */
+export declare class ConfigRefineSource implements RefineSource {
+    private readonly opts;
+    /** Cached metadata, populated by {@link extract} (which the loop runs first). */
+    private metadata;
+    /** Cached surface, populated by {@link extract}; read by {@link guidance}. */
+    private surface;
+    /** Cached implementation-reference grounding, populated by {@link extract}. */
+    private grounding;
+    constructor(opts: ConfigRefineSourceOptions);
+    extract(): Promise<ExtractedSkill>;
+    /**
+     * Map an improvement target to its on-disk location. Config targets carry the
+     * option's dot-path `configKey` as `name` (kind `config-option`); the config
+     * type holds them, so the file is always the config file and the declName is
+     * the type. A `config-example` target points at the same file with no path.
+     */
+    resolveTargetLocation(target: {
+        name: string;
+        kind: string;
+        file?: string;
+    }): TargetLocation | undefined;
+    applyFixes(fixes: readonly DraftedFix[]): Promise<void>;
+    /**
+     * Drafting conventions passed to the model each iteration. Scopes every
+     * routing tag to the single named option, constrains claims to what the type
+     * and provided context can support (the model sees the type, NOT the code that
+     * consumes the config, so unconstrained drafting invents wrong runtime
+     * semantics), and tells it how to draft the `@example` config file. Built from
+     * the cached surface that {@link extract} populates first.
+     */
+    guidance(): string;
+    private loadMetadata;
+    /**
+     * Sibling example path for the config file: same directory, the config file's
+     * base name with any `.ts`/`.tsx`/`.mts`/`.cts` extension replaced by
+     * `.example.ts` (e.g. `z2f.config.ts` → `z2f.config.example.ts`,
+     * `config.ts` → `config.example.ts`).
+     */
+    private exampleFilePath;
+    private loadGrounding;
+    /** Nearest ancestor directory of the config file that holds a package.json. */
+    private findPackageDir;
+}
+//# sourceMappingURL=config-source.d.ts.map

package/dist/refine/config-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-source.d.ts","sourceRoot":"","sources":["../../src/refine/config-source.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE3E,MAAM,WAAW,yBAAyB;IACxC,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IAQzC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPjC,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAsB;IACtC,8EAA8E;IAC9E,OAAO,CAAC,OAAO,CAAqC;IACpD,+EAA+E;IAC/E,OAAO,CAAC,SAAS,CAAM;IAEvB,YAA6B,IAAI,EAAE,yBAAyB,EAAI;IAE1D,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAgDvC;IAED;;;;;OAKG;IACH,qBAAqB,CAAC,MAAM,EAAE;QAC5B,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,cAAc,GAAG,SAAS,CAS7B;IAEK,UAAU,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA2C5D;IAED;;;;;;;OAOG;IACH,QAAQ,IAAI,MAAM,CAoBjB;YAQa,YAAY;IAiB1B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;YAcT,aAAa;IAyC3B,+EAA+E;IAC/E,OAAO,CAAC,cAAc;CAUvB"}

package/dist/refine/config-source.js

@@ -0,0 +1,283 @@
+// packages/core/src/refine/config-source.ts
+import { existsSync } from 'node:fs';
+import { glob, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { extractConfigSurface } from '../config-extract.js';
+import { truncateToTokenBudget } from '../tokens.js';
+import { stripRefineTags, upsertPropertyJsDocTag } from './ast-edit.js';
+import { readPackageMetadata } from './package-metadata.js';
+/** Token cap for the implementation-reference grounding fed to the model. */
+const GROUNDING_TOKEN_CAP = 8000;
+const EXCLUDED_GROUNDING_DIRS = new Set(['node_modules', 'dist', 'build', '.git', 'coverage']);
+/** Maximum directories to walk upward from the config file seeking package.json. */
+const MAX_PACKAGE_LOOKUP_DEPTH = 8;
+/**
+ * {@link RefineSource} for a TypeScript configuration surface.
+ *
+ * Reads the consumer's config type with {@link extractConfigSurface}, exposes it
+ * as a single `config` surface in an {@link ExtractedSkill}, and writes routing
+ * tags back as JSDoc onto the type's individual property declarations. Unlike
+ * the CLI source — whose routing lives at the command (surface) level — a config
+ * surface is documented per-OPTION: each fix targets one property by its
+ * dot-path `configKey` (e.g. `outDir`, `components.prefix`), routed through
+ * {@link upsertPropertyJsDocTag}.
+ *
+ * It also enriches the skill from the package.json nearest the config file (its
+ * description, keywords, repository) and a sibling README, supplying the audit
+ * context the metadata checks (F1/F2/F3/E5/W4/W5/W6) score against — without it
+ * a config skill forfeits those points even when the package already carries
+ * the data.
+ */
+export class ConfigRefineSource {
+    opts;
+    /** Cached metadata, populated by {@link extract} (which the loop runs first). */
+    metadata = {};
+    /** Cached surface, populated by {@link extract}; read by {@link guidance}. */
+    surface;
+    /** Cached implementation-reference grounding, populated by {@link extract}. */
+    grounding = '';
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async extract() {
+        const source = await readFile(this.opts.configFile, 'utf8');
+        const surface = extractConfigSurface(source, this.opts.typeName);
+        if (!surface) {
+            throw new Error(`[skillit] config type '${this.opts.typeName}' not found in ${this.opts.configFile}`);
+        }
+        this.surface = surface;
+        this.grounding = await this.loadGrounding();
+        const meta = await this.loadMetadata();
+        // The render headline (`skill.description`) prefers a caller-supplied
+        // config-specific description so the skill body describes the config surface
+        // rather than the package. `skill.packageDescription` (set below) is kept as
+        // the LITERAL package.json description so the audit's F1 check validates the
+        // real published metadata — a config override must not mask a missing or
+        // too-short package.json description.
+        const description = this.opts.description ?? meta.packageDescription ?? '';
+        const skill = {
+            name: this.opts.name ?? meta.packageName ?? this.opts.typeName,
+            description,
+            functions: [],
+            classes: [],
+            types: [],
+            enums: [],
+            variables: [],
+            examples: [],
+            configSurfaces: [surface]
+        };
+        if (meta.keywords?.length)
+            skill.keywords = meta.keywords;
+        if (meta.repository)
+            skill.repository = meta.repository;
+        if (meta.packageDescription)
+            skill.packageDescription = meta.packageDescription;
+        if (meta.readme !== undefined)
+            skill.readme = meta.readme;
+        // A sibling `<config>.example.ts` (if present) is the skill's usage example
+        // — clears E4 and feeds the rendered Examples section. The refine loop
+        // drafts it once when absent; reading it back here surfaces it thereafter.
+        // Read directly and tolerate ENOENT (no existsSync precheck — that is a
+        // check-then-use race).
+        try {
+            const example = (await readFile(this.exampleFilePath(), 'utf8')).trim();
+            if (example)
+                skill.examples = [example];
+        }
+        catch {
+            // No/unreadable example — leave examples empty (E4 stays a gap).
+        }
+        return skill;
+    }
+    /**
+     * Map an improvement target to its on-disk location. Config targets carry the
+     * option's dot-path `configKey` as `name` (kind `config-option`); the config
+     * type holds them, so the file is always the config file and the declName is
+     * the type. A `config-example` target points at the same file with no path.
+     */
+    resolveTargetLocation(target) {
+        if (target.kind === 'config-example') {
+            return { file: this.opts.configFile, declName: this.opts.typeName };
+        }
+        return {
+            file: this.opts.configFile,
+            declName: this.opts.typeName,
+            propertyPath: target.name
+        };
+    }
+    async applyFixes(fixes) {
+        // An `@example` fix is the drafted config-example FILE, not a JSDoc tag:
+        // write it to the sibling `<config>.example.ts` — but only if one does not
+        // already exist, so a hand-authored example is never clobbered.
+        const exampleFix = fixes.find((fix) => fix.tag === 'example');
+        if (exampleFix) {
+            // Write-if-absent atomically with the `wx` flag (create, fail if exists)
+            // rather than existsSync-then-write — the latter is a TOCTOU race, and the
+            // atomic flag enforces the no-clobber intent at the syscall.
+            try {
+                await writeFile(this.exampleFilePath(), normalizeExampleFile(exampleFix.value), {
+                    encoding: 'utf8',
+                    flag: 'wx'
+                });
+            }
+            catch (error) {
+                // EEXIST = an example already exists; preserve it. Re-throw anything else.
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+        }
+        let source = await readFile(this.opts.configFile, 'utf8');
+        let changed = false;
+        for (const fix of fixes) {
+            if (fix.tag === 'example')
+                continue; // handled above (separate file)
+            // `fix.toolName` is the option's dot-path configKey (set by the
+            // audit-score config-option target). Route it to the matching property.
+            const next = upsertPropertyJsDocTag(source, this.opts.typeName, fix.toolName, fix.tag, fix.value);
+            if (next !== source) {
+                source = next;
+                changed = true;
+            }
+        }
+        if (changed) {
+            await writeFile(this.opts.configFile, source, 'utf8');
+        }
+    }
+    /**
+     * Drafting conventions passed to the model each iteration. Scopes every
+     * routing tag to the single named option, constrains claims to what the type
+     * and provided context can support (the model sees the type, NOT the code that
+     * consumes the config, so unconstrained drafting invents wrong runtime
+     * semantics), and tells it how to draft the `@example` config file. Built from
+     * the cached surface that {@link extract} populates first.
+     */
+    guidance() {
+        const optionList = (this.surface?.options ?? [])
+            .map((o) => `- \`${o.configKey ?? o.name}\`: ${o.type}`)
+            .join('\n');
+        const typeName = this.opts.typeName;
+        return [
+            `You are documenting the individual options of the TypeScript configuration object \`${typeName}\`.`,
+            `Each work item's "Tool" is ONE option, named by its dot-path key (e.g. \`outDir\`, \`components.prefix\`) — except an @example work item, whose "Tool" is the config type \`${typeName}\` itself.`,
+            `For @useWhen / @avoidWhen / @pitfalls: write guidance SPECIFIC to that single option — when to set it (and to what kind of value), when to leave it unset, and footguns unique to its value or interactions. Do NOT describe the configuration type as a whole, the annotate-vs-\`defineConfig()\` choice, or anything that applies to every option; never repeat the same point across options.`,
+            this.grounding
+                ? `GROUND every runtime-behavior claim in the IMPLEMENTATION REFERENCE below (the actual code that consumes this config) and the option's type. State behavior the code actually exhibits — e.g. what an empty array/object means, whether an invalid value throws or is silently ignored, what a flag toggles, how options interact. Do NOT contradict the reference, and do NOT assert behavior absent from both the reference and the type; omit it instead. A confidently wrong "NEVER" is worse than no pitfall.`
+                : `GROUND every claim in the option's TYPE and the documentation provided to you. You can see the type, not the code that reads this config — so do NOT assert runtime behavior you cannot verify: whether an empty array/object means "all" or "none", whether an invalid value throws or is silently ignored, what a boolean flag actually toggles, or how two options interact at runtime. If a behavior is not evidenced by the type or the docs, omit it or phrase it as a type-level fact ("\`mode\` accepts 'submit' | 'auto-save'"). A confidently wrong "NEVER" is worse than no pitfall — prefer fewer, verifiable points over speculative ones.`,
+            `For @example: output a COMPLETE, type-correct example configuration FILE — import statements plus a default export — saved verbatim as a sibling \`*.config.example.ts\` that must compile. Import \`defineConfig\`/\`${typeName}\` from the package by its published name ONLY if the example lives outside that package; if it sits inside the package's own \`src\`, import from the local source entrypoint (a relative path) so the self-import does not resolve to an unbuilt \`dist\`. Use realistic values for required options and a few common optional ones. Output ONLY the file source: no prose, no markdown, no code fences.`,
+            `Options (key: type):\n${optionList}`,
+            ...(this.grounding
+                ? [
+                    `IMPLEMENTATION REFERENCE (the code that consumes this config — ground runtime-behavior claims in it):\n${this.grounding}`
+                ]
+                : [])
+        ].join('\n\n');
+    }
+    /**
+     * Discover and parse the package.json nearest the config file (walking up to
+     * {@link MAX_PACKAGE_LOOKUP_DEPTH} directories) plus a sibling README. Cached
+     * so repeated extract/score passes read the filesystem once. Never throws —
+     * unreadable or absent files just yield empty fields.
+     */
+    async loadMetadata() {
+        const pkgDir = this.findPackageDir();
+        if (!pkgDir)
+            return this.metadata;
+        const meta = await readPackageMetadata(pkgDir);
+        this.metadata = {
+            ...(meta.packageDescription !== undefined
+                ? { packageDescription: meta.packageDescription }
+                : {}),
+            ...(meta.keywords !== undefined ? { keywords: meta.keywords } : {}),
+            ...(meta.repository !== undefined ? { repository: meta.repository } : {}),
+            ...(meta.readme !== undefined ? { readme: meta.readme } : {})
+        };
+        return meta;
+    }
+    /**
+     * Sibling example path for the config file: same directory, the config file's
+     * base name with any `.ts`/`.tsx`/`.mts`/`.cts` extension replaced by
+     * `.example.ts` (e.g. `z2f.config.ts` → `z2f.config.example.ts`,
+     * `config.ts` → `config.example.ts`).
+     */
+    exampleFilePath() {
+        const dir = dirname(this.opts.configFile);
+        const base = basename(this.opts.configFile).replace(/\.[cm]?tsx?$/, '');
+        return join(dir, `${base}.example.ts`);
+    }
+    /**
+     * Read the grounding globs into a single token-capped implementation
+     * reference. Prepends the config module's own declarations (refine tags
+     * stripped — see {@link stripRefineTags}) so preset tables/defaults/validation
+     * ground the model, then appends the matched glob files (skipping `.d.ts`,
+     * excluded dirs, and the already-included config file). Returns `''` when no
+     * globs are configured or nothing matches — never throws.
+     */
+    async loadGrounding() {
+        const globs = this.opts.groundingGlobs;
+        if (!globs?.length)
+            return '';
+        const configAbs = resolve(this.opts.configFile);
+        const seen = new Set([configAbs]);
+        const parts = [];
+        // The config module itself often holds non-type declarations the model
+        // needs to be accurate — preset tables, defaults, `defineConfig`/validation
+        // (e.g. z2f's `SHADCN_OVERRIDES`). Include it, but strip ONLY the routing
+        // tags this source writes back across iterations (so our own accumulated
+        // annotations aren't fed back as "implementation"); hand-authored prose —
+        // the real runtime-behavior grounding — is preserved.
+        const configSource = await readFile(this.opts.configFile, 'utf8').catch(() => '');
+        const configDecls = stripRefineTags(configSource).trim();
+        if (configDecls)
+            parts.push(`// ${this.opts.configFile} (config module declarations)\n${configDecls}`);
+        for (const pattern of globs) {
+            let matches;
+            try {
+                matches = glob(pattern, {
+                    exclude: (f) => f.endsWith('.d.ts') || f.split(/[\\/]/).some((seg) => EXCLUDED_GROUNDING_DIRS.has(seg))
+                });
+            }
+            catch {
+                continue; // bad pattern — skip
+            }
+            for await (const file of matches) {
+                const abs = resolve(file);
+                if (seen.has(abs))
+                    continue; // config file is pre-seeded above
+                seen.add(abs);
+                const content = await readFile(file, 'utf8').catch(() => '');
+                if (content.trim())
+                    parts.push(`// ${file}\n${content.trim()}`);
+            }
+        }
+        if (parts.length === 0)
+            return '';
+        return truncateToTokenBudget(parts.join('\n\n'), GROUNDING_TOKEN_CAP);
+    }
+    /** Nearest ancestor directory of the config file that holds a package.json. */
+    findPackageDir() {
+        let dir = dirname(this.opts.configFile);
+        for (let i = 0; i < MAX_PACKAGE_LOOKUP_DEPTH; i++) {
+            if (existsSync(join(dir, 'package.json')))
+                return dir;
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return undefined;
+    }
+}
+/**
+ * Normalize model-drafted example content into a clean source file: strip a
+ * surrounding markdown code fence if the model added one, and ensure a trailing
+ * newline. The draft is instructed to omit fences, but a chatty backend may add
+ * them anyway.
+ */
+function normalizeExampleFile(raw) {
+    let body = raw.trim();
+    const fenced = body.match(/^```[a-zA-Z]*\n([\s\S]*?)\n```$/);
+    if (fenced?.[1] !== undefined)
+        body = fenced[1].trim();
+    return `${body}\n`;
+}
+//# sourceMappingURL=config-source.js.map