@nanisoft/prism-llms 0.4.0 → 0.5.1

package/dist/extractor.js

@@ -1,42 +1,78 @@
 /**
- * The one props extractor (tickets 12/16): reads prism-ui's built `.d.ts`
- * surface — TSDoc preserved — and returns the Prism-added props. Homed here
- * and exported (`@nanisoft/prism-llms/extractor`) for the site's API tables;
- * one extractor, two consumers. Runs after `^build`, so it reads declarations,
- * never TS source.
+ * The one props extractor.
  *
- * Deliberately compiler-API-free: TypeScript 7 (this repo's compiler) no
- * longer ships the JS compiler API, and ADR-0003 already accepts cosmetic
- * fidelity risk on gnarly unions. This is a small structural scanner for the
- * declaration shape prism-ui emits — `export interface XProps [extends Y]`
- * with JSDoc-carried descriptions. Pass-through re-exports never match, and
- * that absence IS the Extends seam (ADR-0004): no extracted props means the
- * item is "antd X, unchanged".
- */
-/**
- * Extract every exported `*Props` interface from a `.d.ts` source, in source
- * order. Returns an empty array for re-export-only files (pass-throughs).
+ * It reads `@nanisoft/prism-ui`'s emitted declarations, never its TypeScript
+ * source, and it is deliberately compiler-API-free: a small structural scanner
+ * for the declaration shapes this repository emits. Ticket 12 section 2 fixes
+ * the seam at the emitted `.d.ts`, so a compiler bump cannot break the corpus.
+ *
+ * The shapes it understands:
+ * - a named props type (`export type XProps = { ... }` or
+ *   `export interface XProps extends Y { ... }`), referenced by a function;
+ * - an inline props object on the function parameter;
+ * - `ComponentProps<'tag'>`, recorded as an inherited base rather than
+ *   expanded, so a native-backed component reports its element;
+ * - `VariantProps<typeof recipe>`, expanded from the emitted `cva` declaration
+ *   into the recipe's `variant` and `size` rows.
+ *
+ * One extractor, two renderers: the corpus's `## Props` definition list and the
+ * site's API reference table. There is no second extraction.
  */
+function toProp(row) {
+    return {
+        name: row.name,
+        typeText: row.type.replace(/\s+/g, ' ').trim(),
+        required: row.required,
+        ...(row.description ? { description: row.description } : {}),
+        ...(row.default && row.default !== '-' ? { defaultValue: row.default } : {}),
+    };
+}
+/** Extract every exported `*Props` interface from a declaration, in source order. */
 export function extractProps(source) {
     const results = [];
-    const interfacePattern = /export\s+interface\s+(\w+)(?:\s+extends\s+([\w.]+))?\s*\{/g;
+    const pattern = /export\s+interface\s+(\w+)(?:\s+extends\s+([^{}]+?))?\s*\{/g;
     let match;
-    while ((match = interfacePattern.exec(source)) !== null) {
+    while ((match = pattern.exec(source)) !== null) {
         if (!(match[1] ?? '').endsWith('Props'))
-            continue; // supporting types (DocsNavEntry, BlogFrontmatter) are not props
-        const openBrace = interfacePattern.lastIndex - 1;
-        const body = readBalancedBody(source, openBrace);
-        if (body === undefined)
-            continue; // unbalanced — skip rather than guess
+            continue;
+        const openBrace = pattern.lastIndex - 1;
+        const found = readBalancedBody(source, openBrace);
+        if (found === undefined)
+            continue;
         results.push({
             typeName: match[1] ?? '',
-            extendsType: match[2],
-            props: parseProps(body),
+            ...(match[2] ? { extendsType: match[2].trim() } : {}),
+            props: parseMembers(found.body).map(toProp),
         });
     }
     return results;
 }
-/** The `{…}` body of the declaration whose brace sits at `openBrace`, or undefined when unbalanced. */
+/**
+ * Extract the props of the named exports from one declaration file's text.
+ * Exports with no declaration are reported with an empty prop list.
+ */
+export function extractExports(source, exportNames) {
+    return exportNames.map((name) => {
+        const params = findFunctionParams(source, name);
+        if (params === null)
+            return { typeName: name, props: [] };
+        const { props, inherited } = resolveAnnotation(annotationOf(params), source);
+        return {
+            typeName: name,
+            ...(inherited.length > 0 ? { extendsType: inherited.join(' & ') } : {}),
+            props,
+        };
+    });
+}
+/**
+ * The `{...}` body of the declaration whose brace sits at `openBrace`, and the
+ * index of the brace that closed it.
+ *
+ * The index is returned as well as the text because `findTypeBodies` has to
+ * resume scanning after the body, and re-walking it with a second depth counter
+ * is how the two came to disagree. `undefined` for the text means the body never
+ * closed, and the caller stops rather than guessing where it ended.
+ */
 function readBalancedBody(source, openBrace) {
     let depth = 0;
     let i = openBrace;
@@ -66,7 +102,7 @@ function readBalancedBody(source, openBrace) {
         if (ch === '}') {
             depth -= 1;
             if (depth === 0)
-                return source.slice(openBrace + 1, i);
+                return { body: source.slice(openBrace + 1, i), end: i };
         }
         i += 1;
     }
@@ -86,158 +122,265 @@ function skipString(source, start, quote) {
     }
     return -1;
 }
-/** Parse property signatures out of an interface body. Non-signature members (methods, indexers) are skipped. */
-function parseProps(body) {
-    const props = [];
-    let i = 0;
-    let pendingDocs;
-    while (i < body.length) {
-        const trivia = skipTrivia(body, i);
-        i = trivia.next;
-        pendingDocs = trivia.jsDoc ?? pendingDocs;
-        if (i >= body.length)
-            break;
-        const nameMatch = /^([\w$]+)(\?)?\s*:/.exec(body.slice(i));
-        if (!nameMatch) {
-            // Not a property signature (call/construct/index signature, stray token) —
-            // skip to the next statement boundary at depth 0.
-            const boundary = nextTopLevelBoundary(body, i);
-            if (boundary === -1)
-                break;
-            pendingDocs = undefined;
-            i = boundary;
-            continue;
-        }
-        const typeStart = i + nameMatch[0].length;
-        const typeEnd = nextTopLevelBoundary(body, typeStart);
-        const rawType = typeEnd === -1 ? body.slice(typeStart) : body.slice(typeStart, typeEnd);
-        props.push({
-            name: nameMatch[1] ?? '',
-            typeText: normalizeType(rawType),
-            description: pendingDocs?.description,
-            defaultValue: pendingDocs?.defaultValue,
-            required: !nameMatch[2],
-        });
-        pendingDocs = undefined;
-        if (typeEnd === -1)
-            break;
-        i = typeEnd + 1;
-    }
-    return props;
-}
 /**
- * Advance past whitespace/comments. `/**` comments are captured as JSDoc
- * (description + `@defaultValue`), merged across consecutive blocks.
+ * Every object body a named type's declaration holds, in source order.
+ *
+ * A union is published whole or not at all. The single-body form this replaces
+ * took the FIRST match and the first balanced body, so it published one body and
+ * dropped every other by declaration order. For an emitted declaration shaped
+ * `Common & ({ A } | { B })` it published neither arm at all, only the shared
+ * part, so the API table described a type the declaration does not describe: the
+ * `bare` arm of a union was invisible to every reader and every agent. A
+ * type-level truth the extractor drops becomes a documentation-level lie, so the
+ * scan walks every balanced body inside the declaration's own extent instead.
+ *
+ * The depth and angle tracking is load-bearing rather than defensive. A member
+ * semicolon sits at depth 1, so a scan that stopped on the first `;` would end
+ * the declaration at `variant?: 'icon';` and never reach the second arm, which
+ * is the defect this function exists to remove. Angle brackets are tracked
+ * because a generic argument can carry its own braces.
+ *
+ * **A body is consumed once and skipped, not re-walked.** `readBalancedBody`
+ * returns a body's text, and the scan used to leave `i` on the opening brace and
+ * walk the body a second time with its own depth counter. The second walk counts
+ * every `{` the balanced read had already accounted for, so the two disagreed and
+ * `depth` could not be trusted to reach 0 at the brace that closed the body. The
+ * scan therefore depended on finding a terminator it was no longer counting
+ * correctly, and the caller concatenates the emitted JavaScript of the same
+ * module beside the declaration, so a scan that ran long published every object
+ * literal in that implementation as another arm of the type. Advancing `i` to the
+ * brace `readBalancedBody` reported removes the second walk rather than trying to
+ * correct for it, and one walk cannot disagree with itself.
+ *
+ * The honest limit on that claim: a declaration whose body closes and is followed
+ * immediately by a terminator terminated the scan correctly even before this
+ * change, which is why every Page in the package was published correctly and only
+ * the first Page with a two-line barrel was not. The defect was a miscount, not a
+ * missing terminator, and a miscount is only visible where a miscount is.
  */
-function skipTrivia(source, start) {
-    let i = start;
-    let jsDoc;
-    while (i < source.length) {
-        const ch = source[i] ?? '';
-        if (/\s/.test(ch)) {
-            i += 1;
-            continue;
-        }
-        if (ch === '/' && source[i + 1] === '*' && source[i + 2] === '*') {
-            const close = source.indexOf('*/', i + 3);
-            if (close === -1)
-                return { next: source.length };
-            // Consecutive JSDoc blocks merge — a description and a @defaultValue may
-            // live in separate blocks (tsc emits one, hand-written d.ts may not).
-            const parsed = readJsDoc(source.slice(i + 3, close));
-            if (parsed) {
-                jsDoc = {
-                    description: jsDoc?.description ?? parsed.description,
-                    defaultValue: jsDoc?.defaultValue ?? parsed.defaultValue,
-                };
-            }
-            i = close + 2;
+function findTypeBodies(source, name) {
+    const pattern = new RegExp(`(?:export\\s+)?(?:type|interface)\\s+${name}\\b`);
+    const match = pattern.exec(source);
+    if (!match)
+        return [];
+    const bodies = [];
+    let depth = 0;
+    let angle = 0;
+    let quote = null;
+    let i = match.index + match[0].length;
+    for (; i < source.length; i += 1) {
+        const ch = source[i];
+        if (quote !== null) {
+            if (ch === quote && source[i - 1] !== '\\')
+                quote = null;
             continue;
         }
-        if (ch === '/' && source[i + 1] === '*') {
-            const close = source.indexOf('*/', i + 2);
-            if (close === -1)
-                return { next: source.length };
-            i = close + 2;
+        if (ch === '"' || ch === "'" || ch === '`') {
+            quote = ch;
             continue;
         }
-        if (ch === '/' && source[i + 1] === '/') {
-            const close = source.indexOf('\n', i);
-            if (close === -1)
-                return { next: source.length };
-            i = close;
+        if (ch === '{') {
+            const found = readBalancedBody(source, i);
+            if (found === undefined)
+                return bodies;
+            bodies.push(found.body);
+            // Resume AFTER the brace that closed the body. The re-walk this replaces
+            // counted every `{` in the body a second time and only the closing `}`
+            // once, so `depth` never returned to 0 and the scan never terminated.
+            i = found.end;
             continue;
         }
-        return { next: i, jsDoc };
+        if (ch === '(')
+            depth += 1;
+        else if (ch === ')')
+            depth -= 1;
+        else if (ch === '<')
+            angle += 1;
+        else if (ch === '>')
+            angle = Math.max(0, angle - 1);
+        // The declaration ends at the first terminator that closes nothing it
+        // opened, so the next declaration's braces cannot be collected as arms.
+        else if ((ch === ';' || ch === '\n') && depth <= 0 && angle === 0)
+            return bodies;
     }
-    return { next: i, jsDoc };
+    return bodies;
 }
-function readJsDoc(text) {
-    const lines = text
-        .split('\n')
-        .map((line) => line.replace(/^\s*\*/, '').trim());
-    const description = [];
-    let defaultValue;
-    for (const line of lines) {
-        if (!line) {
-            if (description.length > 0)
-                description.push('');
-            continue;
-        }
-        const tag = /^@(\w+)\s*(.*)$/.exec(line);
-        if (tag) {
-            if (tag[1] === 'defaultValue')
-                defaultValue = tag[2] || undefined;
-            continue; // other tags (@example, @internal, …) stay out of the docs
-        }
-        description.push(line);
+function findFunctionParams(source, name) {
+    const pattern = new RegExp(`declare\\s+function\\s+${name}\\s*\\(`);
+    const match = pattern.exec(source);
+    if (!match)
+        return null;
+    const start = match.index + match[0].length;
+    let depth = 1;
+    let quote = null;
+    let i = start;
+    for (; i < source.length; i += 1) {
+        const ch = source[i];
+        if (quote) {
+            if (ch === quote && source[i - 1] !== '\\')
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === '`')
+            quote = ch;
+        else if (ch === '(')
+            depth += 1;
+        else if (ch === ')') {
+            depth -= 1;
+            if (depth === 0)
+                break;
+        }
     }
-    const joined = description.join(' ').trim();
-    if (!joined && !defaultValue)
-        return undefined;
-    return { description: joined || undefined, defaultValue };
+    return source.slice(start, i);
 }
-/** Index of the next `;` or `,` at bracket depth 0 (starting at `from`), or -1. */
-function nextTopLevelBoundary(source, from) {
+function annotationOf(params) {
     let depth = 0;
-    let i = from;
-    while (i < source.length) {
-        const ch = source[i];
-        if (ch === '/' && source[i + 1] === '*') {
-            const close = source.indexOf('*/', i + 2);
-            if (close === -1)
-                return -1;
-            i = close + 2;
+    let angle = 0;
+    let quote = null;
+    for (let i = 0; i < params.length; i += 1) {
+        const ch = params[i];
+        if (quote) {
+            if (ch === quote && params[i - 1] !== '\\')
+                quote = null;
             continue;
         }
-        if (ch === '/' && source[i + 1] === '/') {
-            const close = source.indexOf('\n', i);
-            if (close === -1)
-                return -1;
-            i = close;
+        if (ch === '"' || ch === "'" || ch === '`')
+            quote = ch;
+        else if (ch === '(' || ch === '{' || ch === '[')
+            depth += 1;
+        else if (ch === ')' || ch === '}' || ch === ']')
+            depth -= 1;
+        else if (ch === '<')
+            angle += 1;
+        else if (ch === '>')
+            angle = Math.max(0, angle - 1);
+        else if (ch === ':' && depth === 0 && angle === 0)
+            return params.slice(i + 1).trim();
+    }
+    return null;
+}
+function variantRows(source, recipeName) {
+    const pattern = new RegExp(`declare const ${recipeName}\\s*:\\s*\\(props\\?:\\s*\\(\\{([\\s\\S]*?)\\}\\s*&`);
+    const match = pattern.exec(source);
+    return match ? parseMembers(match[1] ?? '') : [];
+}
+function resolveAnnotation(annotation, source) {
+    if (!annotation)
+        return { props: [], inherited: [] };
+    const named = /^[A-Za-z_$][\w$]*$/.test(annotation) ? findTypeBodies(source, annotation) : [];
+    if (named.length > 0) {
+        // Every arm, in declaration order, so a union reaches the table whole
+        // rather than as whichever arm happened to be written first.
+        return { props: named.flatMap((body) => parseMembers(body)).map(toProp), inherited: [] };
+    }
+    if (annotation.startsWith('{')) {
+        const found = readBalancedBody(annotation, 0);
+        if (found !== undefined)
+            return { props: parseMembers(found.body).map(toProp), inherited: [] };
+    }
+    const props = [];
+    const inherited = [];
+    const recipe = /VariantProps<typeof (\w+)>/.exec(annotation);
+    if (recipe)
+        props.push(...variantRows(source, recipe[1] ?? '').map(toProp));
+    const componentProps = /ComponentProps<'([^']+)'>/.exec(annotation);
+    if (componentProps)
+        inherited.push(`React.ComponentProps<'${componentProps[1]}'>`);
+    if (props.length === 0 && inherited.length === 0) {
+        inherited.push(annotation.replace(/\s+/g, ' ').slice(0, 200));
+    }
+    return { props, inherited };
+}
+function splitTopLevel(body) {
+    const parts = [];
+    let depth = 0;
+    let angle = 0;
+    let quote = null;
+    let current = '';
+    for (let i = 0; i < body.length; i += 1) {
+        const ch = body[i];
+        if (!quote && ch === '/' && body[i + 1] === '*') {
+            const end = body.indexOf('*/', i + 2);
+            const stop = end < 0 ? body.length : end + 2;
+            current += body.slice(i, stop);
+            i = stop - 1;
+            continue;
+        }
+        if (!quote && ch === '/' && body[i + 1] === '/') {
+            const end = body.indexOf('\n', i + 2);
+            const stop = end < 0 ? body.length : end;
+            current += body.slice(i, stop);
+            i = stop - 1;
+            continue;
+        }
+        if (quote) {
+            current += ch;
+            if (ch === quote && body[i - 1] !== '\\')
+                quote = null;
             continue;
         }
         if (ch === '"' || ch === "'" || ch === '`') {
-            i = skipString(source, i, ch);
-            if (i === -1)
-                return -1;
+            quote = ch;
+            current += ch;
             continue;
         }
-        if (ch === '(' || ch === '[' || ch === '{' || ch === '<')
+        if (ch === '(' || ch === '{' || ch === '[')
             depth += 1;
-        if (ch === ')' || ch === ']' || ch === '}' || ch === '>')
+        else if (ch === ')' || ch === '}' || ch === ']')
             depth -= 1;
-        if (depth === 0 && (ch === ';' || ch === ','))
-            return i;
-        i += 1;
+        else if (ch === '<')
+            angle += 1;
+        else if (ch === '>')
+            angle = Math.max(0, angle - 1);
+        if (ch === ';' && depth <= 0 && angle === 0) {
+            parts.push(current);
+            current = '';
+            continue;
+        }
+        current += ch;
     }
-    return -1;
+    if (current.trim())
+        parts.push(current);
+    return parts;
 }
-/** Collapse comments and newlines to single spaces — readable, verbatim type text. */
-function normalizeType(raw) {
-    return raw
-        .replace(/\/\*[\s\S]*?\*\//g, ' ')
-        .replace(/\s+/g, ' ')
+function parseJsdoc(text) {
+    const match = /\/\*\*([\s\S]*?)\*\//.exec(text);
+    if (!match)
+        return { description: '', defaultValue: '' };
+    let content = match[1] ?? '';
+    let defaultValue = '';
+    const tag = /@defaultValue\s+([^\s*]+)/.exec(content);
+    if (tag) {
+        defaultValue = tag[1] ?? '';
+        content = content.replace(tag[0], ' ');
+    }
+    const description = content
+        .split('\n')
+        .map((line) => line.replace(/^\s*\*?\s?/, '').trim())
+        .filter((line) => line && !line.startsWith('@'))
+        .join(' ')
         .trim();
+    return { description, defaultValue };
+}
+function parseMembers(body) {
+    const rows = [];
+    for (const part of splitTopLevel(body)) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const comment = /\/\*\*([\s\S]*?)\*\//.exec(trimmed);
+        const rest = comment ? trimmed.slice(comment.index + comment[0].length) : trimmed;
+        const { description, defaultValue } = parseJsdoc(trimmed);
+        const member = /^([A-Za-z_$][\w$]*)\s*(\?)?\s*:\s*([\s\S]+)$/.exec(rest.trim());
+        if (!member)
+            continue;
+        rows.push({
+            name: member[1] ?? '',
+            type: (member[3] ?? '').replace(/;\s*$/, '').trim(),
+            required: !member[2],
+            default: defaultValue || '-',
+            description,
+        });
+    }
+    return rows;
 }
-//# sourceMappingURL=extractor.js.map

package/dist/index.d.ts

@@ -1,10 +1,15 @@
 /**
- * prism-llms public surface. The root stays compiler-free (the extractor sits
- * behind `./extractor`); what ships here is the Markdown lane every consumer
- * of the corpus shares — the site's stub/API tooling imports these helpers so
- * it renders exactly what the generator emits.
+ * prism-llms public surface.
+ *
+ * The store contract is exported from the root; the extractor sits behind the
+ * `./extractor` subpath and is shared with the site's API reference table. The
+ * Markdown lane and the demo contract ship so a consumer renders exactly what
+ * the generator emits.
  */
-export { parseMdx, fence, renderComponentDemos, stripMdxMechanics, renderTable, renderPropsSection, type DocMeta, type ParsedMdx, } from './markdown.js';
+export { parsePrismDocsStore, STORE_CATEGORIES, STORE_KINDS, STORE_MODES, STORE_PACKS, STORE_SCALE_GROUPS, STORE_SECTIONS, STORE_SECTION_TITLES, STORE_STATUSES, } from './store.js';
+export type { Mode, PackId, PrismChangelog, PrismChangelogRelease, PrismDocsExample, PrismDocsPage, PrismDocsStore, PrismDocsStoreEntry, PrismScaleGroup, PrismScaleToken, PrismSemanticToken, PrismThemeTokens, PrismTokensProjection, StoreKind, StoreSection, StoreStatus, TokenGroup, } from './store.js';
+export { assembleDoc, demoTitle, fence, parseMdx, parsePropLine, renderCompositionSection, renderCrossReferences, renderDemoSection, renderPropLine, renderPropsBody, renderPropsSection, stripMdxMechanics, stripSection, } from './markdown.js';
+export type { CompositionField, CrossReference, DocMeta, ParsedMdx, ParsedPropLine, } from './markdown.js';
 export type { ExtractedInterface, ExtractedProp } from './extractor.js';
-export { scanPrismImports, validateDemoSource, type DemoViolation } from './demo-graph.js';
-//# sourceMappingURL=index.d.ts.map
+export { scanPrismImports, scanPrismImportsWithSource, validateDemoSource, } from './demo-graph.js';
+export type { DemoViolation, PrismImport } from './demo-graph.js';

package/dist/index.js

@@ -1,9 +1,11 @@
 /**
- * prism-llms public surface. The root stays compiler-free (the extractor sits
- * behind `./extractor`); what ships here is the Markdown lane every consumer
- * of the corpus shares — the site's stub/API tooling imports these helpers so
- * it renders exactly what the generator emits.
+ * prism-llms public surface.
+ *
+ * The store contract is exported from the root; the extractor sits behind the
+ * `./extractor` subpath and is shared with the site's API reference table. The
+ * Markdown lane and the demo contract ship so a consumer renders exactly what
+ * the generator emits.
  */
-export { parseMdx, fence, renderComponentDemos, stripMdxMechanics, renderTable, renderPropsSection, } from './markdown.js';
-export { scanPrismImports, validateDemoSource } from './demo-graph.js';
-//# sourceMappingURL=index.js.map
+export { parsePrismDocsStore, STORE_CATEGORIES, STORE_KINDS, STORE_MODES, STORE_PACKS, STORE_SCALE_GROUPS, STORE_SECTIONS, STORE_SECTION_TITLES, STORE_STATUSES, } from './store.js';
+export { assembleDoc, demoTitle, fence, parseMdx, parsePropLine, renderCompositionSection, renderCrossReferences, renderDemoSection, renderPropLine, renderPropsBody, renderPropsSection, stripMdxMechanics, stripSection, } from './markdown.js';
+export { scanPrismImports, scanPrismImportsWithSource, validateDemoSource, } from './demo-graph.js';