@clay-design-system/kb 0.0.0-stage → 0.14.0

package/dist/core/prose.js

@@ -0,0 +1,106 @@
+/**
+ * Prose utilities for the general `kb:lint` claim checks (K3 retry 2): split a unit into sentences,
+ * reduce a sentence to its significant tokens, and weigh tokens by rarity (IDF) over the corpus.
+ *
+ * Normalisation is deliberately simple and symmetric (both sides of every comparison go through it):
+ *   - unit-id citations (`policy.x.y`) are removed (a citation is a link, not content);
+ *   - Markdown punctuation is dropped; `gray` → `grey`; "back to back" / "next to each other" /
+ *     "adjacent" / "consecutive" / "in a row" → `adjacent`;
+ *   - numbers keep their unit (`64 px` → `64px`) and ranges become one token (`4–6` → `4to6`);
+ *   - identifiers are split on `-` / `_` / camelCase is kept whole (`tabs-background` → tabs, background;
+ *     `FeaturesSection` → featuressection);
+ *   - English stop words and normative words (never/always/must/only/…) are not significant: the
+ *     normative words mark a *rule* sentence but never count as shared content;
+ *   - a light stemmer folds plurals and -ing/-ed.
+ */
+import { stem } from './rank.js';
+export const UNIT_ID_RE = /`?\b(?:rule|policy|procedure|section|layout|component|item|limit|token|breakpoint|asset|recipe|gotcha|brand|stat|background|page|skill)\.[A-Za-z0-9][A-Za-z0-9_.+-]*[A-Za-z0-9]`?/g;
+/** A sentence carries a rule when it says what to always / never / only do. */
+export const NORMATIVE_RE = /\b(?:never|always|must|should|don'?t|do not|does not|doesn'?t|only|at most|at least|no more than|max(?:imum)?|min(?:imum)?|avoid|required?|not|cannot|can'?t|no)\b|≤|≥/i;
+/**
+ * A sentence gives an instruction without a normative word: it opens with a base verb, optionally after a leading
+ * "When/Whenever/If …," clause ("Whenever a MediaSlot is a placeholder, give it a placeholderLabel …"). K4: candidate
+ * restatements are normative OR imperative sentences.
+ */
+export const IMPERATIVE_RE = /^(?:[-*]\s*)?(?:\*\*)?(?:(?:when|whenever|if|for|on|in)\b[^,]{3,80},\s*)?(?:add|avoid|choose|give|keep|label|make|name|pair|pass|pick|place|prefer|put|render|set|show|state|use|write|cap|limit|mark|wrap|split|stack|lead|open|close|end|start|ship)\b/i;
+const STOP = new Set(('a an and are as at be been being but by can could did do does doing for from had has have having he her here hers his how i if in into is it its ' +
+    'itself just me more most my of off on once or other our out over own same she so some such than that the their them then there these they this ' +
+    'those through to too under until up very was we were what when where which while who whom why will with would you your yours each both few ' +
+    'any all also via per e g eg ie etc one use used using get gets set sets like make makes made way thing things whose instead').split(' '));
+const NORMATIVE_WORDS = new Set('never always must should dont don do not doesnt does only most least no more than max maximum min minimum avoid require required cannot cant'.split(' '));
+/** The light stemmer (folds plurals, -ing/-ed) lives with the search analyzer so lint and search stem alike. */
+export { stem };
+/** Text with citations, Markdown and phrasing variants normalised (still human-readable). */
+export function normaliseText(s) {
+    return s
+        .replace(UNIT_ID_RE, ' ')
+        .replace(/\bgray\b/gi, 'grey')
+        .replace(/\b(?:back[\s-]to[\s-]back|next to each other|side by side with each other|adjacent(?:ly)?|consecutive(?:ly)?|in a row)\b/gi, ' adjacent ')
+        .replace(/(\d+)\s?px\b/gi, '$1px')
+        .replace(/(?<![\d.])(\d+)\s?[–—-]\s?(\d+)(?![\d.])/g, '$1to$2');
+}
+/** Significant, stemmed tokens of a sentence (a set). */
+export function sigTokens(s) {
+    const out = new Set();
+    const t = normaliseText(s)
+        .replace(/[*_`>#|"'“”‘’()[\]{}]/g, ' ')
+        .toLowerCase();
+    for (const raw of t.split(/[^a-z0-9%]+/)) {
+        if (!raw)
+            continue;
+        if (raw.length < 2 && !/^\d$/.test(raw))
+            continue;
+        if (STOP.has(raw) || NORMATIVE_WORDS.has(raw))
+            continue;
+        out.add(stem(raw));
+    }
+    return out;
+}
+export const isNumericToken = (t) => /^\d/.test(t);
+/** Sentences of a Markdown body: one per table row / list item / line, lines split on `. ` + capital and (unless `keepSemicolons`) on `; `. Code fences are skipped. */
+export function sentences(text, opts = {}) {
+    const out = [];
+    let fence = false;
+    for (const line of text.split('\n')) {
+        if (/^\s*```/.test(line)) {
+            fence = !fence;
+            continue;
+        }
+        if (fence)
+            continue;
+        const l = line.trim();
+        if (!l || /^\|?\s*:?-{3,}/.test(l))
+            continue;
+        if (l.startsWith('|')) {
+            out.push(l);
+            continue;
+        }
+        const parts = opts.keepSemicolons
+            ? l.split(/(?<=[.!?])\s+(?=[A-Z`*(“"])/)
+            : l.split(/(?<=[.;!?])\s+(?=[A-Z`*(“"])|(?<=;)\s+/);
+        for (const part of parts)
+            if (part.trim().length > 2)
+                out.push(part.trim());
+    }
+    return out;
+}
+/** Inverse document frequency over a corpus of token sets: rare tokens weigh more. */
+export function idfOf(docs) {
+    const df = new Map();
+    let n = 0;
+    for (const d of docs) {
+        n++;
+        for (const t of d)
+            df.set(t, (df.get(t) ?? 0) + 1);
+    }
+    return (t) => Math.log((n + 1) / ((df.get(t) ?? 0) + 1)) + 1;
+}
+export function intersect(a, b) {
+    const out = [];
+    const [small, big] = a.size <= b.size ? [a, b] : [b, a];
+    for (const x of small)
+        if (big.has(x))
+            out.push(x);
+    return out;
+}
+//# sourceMappingURL=prose.js.map

package/dist/core/prose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prose.js","sourceRoot":"","sources":["../../src/core/prose.ts"],"names":[],"mappings":"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"}

package/dist/core/query.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Answer formatters for search, get, section, rules, and route.
+ * Same `{ text, data }` the CLI and MCP return. No filesystem: a caller that has a brief
+ * file reads it and passes `brief`.
+ */
+import type { MemorySession as Session } from './memory.js';
+import type { Kb, KbUnit, Stage } from './model.js';
+import { estimateTokens } from './model.js';
+import type { RouteOptions } from './route.js';
+import type { SearchHit, SearchOptions, SearchSource } from './search.js';
+export interface Out<T> {
+    text: string;
+    data: T;
+}
+export interface QueryCtx {
+    kb: Kb;
+    /** What `search` and `route` rank with: an in-memory index (a snapshot, the files) or a searcher (the registry). */
+    index: SearchSource;
+    byId: Map<string, KbUnit>;
+}
+type Ctx = QueryCtx;
+export declare const tokensOf: typeof estimateTokens;
+export declare const tight: (body: string) => string;
+/** Full units. An id ending in `*` expands to every id with that prefix (max 25). */
+export declare function get(ctx: Ctx, ids: string[], opts?: {
+    session?: Session;
+    full?: boolean;
+}): Out<{
+    units: KbUnit[];
+    missing: string[];
+    repeated: string[];
+}>;
+/**
+ * K11: a long string-literal union in a code span (`'activity' \| 'airplay' \| …`, 597 icon names) is clipped to its
+ * first few members plus the count; `get --full` prints it whole. When the values are icon names, the line says how
+ * to look one up instead.
+ */
+export declare function clipUnions(ctx: Ctx, body: string): string;
+/**
+ * `clay search --each a,b,c` (K11): one search per term, the best hit(s) for each — resolves several brand / icon /
+ * section names in one call (`--limit n` per term, default 1).
+ */
+export declare function searchEach(ctx: Ctx, termsList: string[], opts?: SearchOptions): Out<{
+    results: {
+        term: string;
+        hits: SearchHit[];
+    }[];
+}>;
+export declare function search(ctx: Ctx, query: string, opts?: SearchOptions): Out<{
+    hits: SearchHit[];
+}>;
+/**
+ * `--session` (K8): units this build was already served are named, not repeated; Watch drops lines it saw and units
+ * about sections it never looked at. `--since <stage>`: the same dedupe without a session file — the routes of
+ * `<stage>` up to the stage before this one (same skill and mode) count as served.
+ */
+export declare function route(ctx: Ctx, opts: RouteOptions & {
+    briefPath?: string;
+    session?: Session;
+    since?: Stage;
+}): {
+    text: string;
+    data: import("./route.js").RouteResult;
+};
+/** `clay section` with no name (K8): every web section with its layouts and use, plus the atoms `clay section` also takes. */
+export declare function sectionList(ctx: Ctx, opts?: {
+    scope?: 'email';
+}): Out<{
+    sections: string[];
+}>;
+export declare function section(ctx: Ctx, name: string, layout?: string, opts?: {
+    session?: Session;
+    compact?: boolean;
+}): Out<{
+    section: string;
+    layout?: string;
+    units: string[];
+}>;
+export declare function rules(ctx: Ctx, opts?: {
+    stage?: Stage;
+    mode?: 'A' | 'B';
+    scope?: 'email' | 'web';
+}): Out<{
+    units: string[];
+}>;
+export {};
+//# sourceMappingURL=query.d.ts.map

package/dist/core/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/core/query.ts"],"names":[],"mappings":"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"}