@urbicon-ui/mcp-server 6.1.5 → 6.1.6

package/src/design-linter/tokens.test.ts

@@ -1,80 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { describe, expect, it } from 'vitest';
-import { VALID_TOKEN_CORES } from './tokens.js';
-
-/**
- * Drift guard: the hardcoded {@link VALID_TOKEN_CORES} is the mcp-server's
- * standalone copy of the design tokens. When the blocks CSS source is present
- * (i.e. running inside the monorepo) we re-derive the token cores from it and
- * assert the two agree exactly. Any token added to / removed from the CSS that
- * is not mirrored here will fail this test — keeping the hallucination detector
- * honest. The mcp-server ships without the CSS, so this can only run in-repo.
- */
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const styleDir = resolve(__dirname, '..', '..', '..', 'blocks', 'src', 'lib', 'style');
-const foundation = resolve(styleDir, 'foundation.css');
-const semantic = resolve(styleDir, 'semantic.css');
-const cssAvailable = existsSync(foundation) && existsSync(semantic);
-
-/** Token cores that intentionally live in CSS but are NOT colour-utility cores. */
-const EXCLUDED_PREFIXES = ['shadow-']; // shadows are used via `shadow-[var(--blocks-shadow-*)]`, not `bg-shadow-*`
-
-function deriveCoresFromCss(): Set<string> {
-  const cores = new Set<string>();
-  for (const file of [foundation, semantic]) {
-    const css = readFileSync(file, 'utf-8');
-    for (const m of css.matchAll(/--color-([a-z0-9-]+)\s*:/g)) {
-      const core = m[1]!;
-      if (EXCLUDED_PREFIXES.some((p) => core.startsWith(p))) continue;
-      cores.add(core);
-    }
-  }
-  return cores;
-}
-
-describe.skipIf(!cssAvailable)('token whitelist drift guard', () => {
-  it('recognises every colour token defined in the CSS (no forgotten additions)', () => {
-    const cssCores = deriveCoresFromCss();
-    const missing = [...cssCores].filter((c) => !VALID_TOKEN_CORES.has(c)).sort();
-    expect(missing, `CSS tokens missing from VALID_TOKEN_CORES: ${missing.join(', ')}`).toEqual([]);
-  });
-
-  it('contains no phantom tokens absent from the CSS (no invented entries)', () => {
-    const cssCores = deriveCoresFromCss();
-    const phantom = [...VALID_TOKEN_CORES].filter((c) => !cssCores.has(c)).sort();
-    expect(
-      phantom,
-      `Entries in VALID_TOKEN_CORES with no matching --color-* in CSS: ${phantom.join(', ')}`
-    ).toEqual([]);
-  });
-
-  it('each EXCLUDED_PREFIX still matches a real CSS token (exclusion not stale)', () => {
-    const css = readFileSync(foundation, 'utf-8') + readFileSync(semantic, 'utf-8');
-    for (const prefix of EXCLUDED_PREFIXES) {
-      expect(
-        css,
-        `EXCLUDED_PREFIX "${prefix}" no longer matches any --color-* token — may be stale`
-      ).toMatch(new RegExp(`--color-${prefix}`));
-    }
-  });
-});
-
-describe('token whitelist shape', () => {
-  it('includes representative tokens from each family', () => {
-    for (const core of [
-      'surface-base',
-      'text-primary',
-      'border-subtle',
-      'primary',
-      'primary-500',
-      'feedback-success-subtle',
-      'interactive-hover',
-      'chart-1'
-    ]) {
-      expect(VALID_TOKEN_CORES.has(core), core).toBe(true);
-    }
-  });
-});

package/src/design-linter/tokens.ts

@@ -1,203 +0,0 @@
-/**
- * The authoritative set of Urbicon UI semantic design tokens, expressed as the
- * "core" of a Tailwind colour utility (the part after `bg-`/`text-`/`border-`/…).
- *
- * SOURCE OF TRUTH: `packages/blocks/src/lib/style/{foundation,semantic}.css`
- * (the `--color-*` custom properties). This list is hand-maintained but guarded
- * against drift by `tokens.test.ts`, which re-derives the set from the CSS when
- * run inside the monorepo and fails on any mismatch. The mcp-server ships
- * standalone (no access to the blocks source at runtime), so the data must live
- * here, not be read from disk.
- *
- * Why a whitelist: token hallucination is the single biggest weakness of
- * design-quality guidance — the model invents plausible names like
- * `bg-status-danger` or `text-success-fg`
- * that do not exist. A deterministic whitelist turns that from a guess into a
- * fact: a utility whose core looks semantic but is absent here is flagged.
- */
-
-/** Surface background tokens → `bg-surface-*`. */
-const SURFACE_CORES = [
-  'surface-base',
-  'surface-quiet',
-  'surface-subtle',
-  'surface-elevated',
-  'surface-overlay',
-  'surface-interactive',
-  'surface-hover',
-  'surface-active',
-  'surface-disabled',
-  'surface-selected',
-  'surface-inverted'
-] as const;
-
-/** Text colour tokens → `text-text-*` (the `text-` namespace, used after a colour prefix). */
-const TEXT_CORES = [
-  'text-primary',
-  'text-secondary',
-  'text-tertiary',
-  'text-quaternary',
-  'text-disabled',
-  'text-inverted',
-  'text-on-primary',
-  'text-on-dark',
-  'text-on-surface'
-] as const;
-
-/** Border colour tokens → `border-border-*`. */
-const BORDER_CORES = [
-  'border-subtle',
-  'border-default',
-  'border-emphasis',
-  'border-strong',
-  'border-hairline'
-] as const;
-
-/** Intent palettes. Each has a bare token plus the four interaction variants. */
-const INTENT_NAMES = [
-  'primary',
-  'secondary',
-  'success',
-  'warning',
-  'danger',
-  'info',
-  'neutral'
-] as const;
-
-const INTENT_VARIANTS = ['hover', 'active', 'subtle', 'emphasis'] as const;
-
-/** Numbered foundation steps present on every intent scale. */
-const SCALE_STEPS = [
-  '50',
-  '100',
-  '200',
-  '300',
-  '400',
-  '500',
-  '600',
-  '700',
-  '800',
-  '900',
-  '950'
-] as const;
-
-/**
- * `neutral` carries an extended ramp beyond the standard scale (finer steps for
- * the surface ladder). Omitting these would make the hallucination rule flag a
- * real token like `bg-neutral-650` — the drift guard in tokens.test.ts caught
- * exactly that.
- */
-const NEUTRAL_EXTRA_STEPS = ['0', '25', '650', '750', '850'] as const;
-
-/** Warm-neutral foundation scale (used by the Organic/Warm paradigm). Scale-only — no semantic variants. */
-const WARM_NEUTRAL_STEPS = SCALE_STEPS;
-
-/** Feedback tokens for status messaging → `bg-feedback-*` / `text-feedback-*`. */
-const FEEDBACK_CORES = [
-  'feedback-info',
-  'feedback-info-subtle',
-  'feedback-success',
-  'feedback-success-subtle',
-  'feedback-warning',
-  'feedback-warning-subtle',
-  'feedback-error',
-  'feedback-error-subtle'
-] as const;
-
-/** Interactive overlay tokens. */
-const INTERACTIVE_CORES = [
-  'interactive-hover',
-  'interactive-active',
-  'interactive-focus',
-  'interactive-disabled'
-] as const;
-
-/** Chart series tokens → `text-chart-1` … `text-chart-6`. */
-const CHART_CORES = ['chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5', 'chart-6'] as const;
-
-function buildIntentCores(): string[] {
-  const cores: string[] = [];
-  for (const intent of INTENT_NAMES) {
-    cores.push(intent); // bare, e.g. `bg-primary`
-    for (const variant of INTENT_VARIANTS) cores.push(`${intent}-${variant}`); // `bg-primary-subtle`
-    for (const step of SCALE_STEPS) cores.push(`${intent}-${step}`); // `bg-primary-500`
-  }
-  return cores;
-}
-
-/**
- * Every valid semantic colour-utility core, as a Set for O(1) membership checks.
- * `surface-base`, `text-primary`, `primary`, `primary-500`, `feedback-success`, …
- */
-export const VALID_TOKEN_CORES: ReadonlySet<string> = new Set([
-  ...SURFACE_CORES,
-  ...TEXT_CORES,
-  ...BORDER_CORES,
-  ...buildIntentCores(),
-  ...NEUTRAL_EXTRA_STEPS.map((s) => `neutral-${s}`),
-  ...WARM_NEUTRAL_STEPS.map((s) => `warm-neutral-${s}`),
-  ...FEEDBACK_CORES,
-  ...INTERACTIVE_CORES,
-  ...CHART_CORES
-]);
-
-/**
- * Namespaces that mark a utility core as "intended to be semantic". A core that
- * starts with one of these but is NOT in {@link VALID_TOKEN_CORES} is a
- * hallucinated token. Kept deliberately narrow so we never flag genuine Tailwind
- * utilities (`bg-transparent`, `bg-cover`, arbitrary `bg-[#fff]`).
- */
-export const SEMANTIC_NAMESPACES = [
-  'surface-',
-  'text-',
-  'border-',
-  'feedback-',
-  'interactive-',
-  'chart-'
-] as const;
-
-/** Intent prefixes (`primary-…`, `success-…`) that mark a core as semantic-intent. */
-export const INTENT_PREFIXES: readonly string[] = INTENT_NAMES;
-
-/**
- * The shadcn/ui (and Radix) token vocabulary. This is the single most common
- * hallucination source: with no explicit whitelist, models default to the
- * dominant design-system convention in their training data — `text-foreground`,
- * `bg-accent`, `text-muted-foreground`, `bg-card`, … — none of which exist in
- * Urbicon UI. Discovered empirically during design-quality evaluation.
- * These bare cores slip past the namespace/intent heuristics, so they are
- * matched explicitly. (Suffix `-foreground` and the `fg`/`fg-` family are caught
- * by rule in rules.ts.)
- */
-export const KNOWN_FOREIGN_CORES: ReadonlySet<string> = new Set([
-  'foreground',
-  'background',
-  'muted',
-  'accent',
-  'card',
-  'popover',
-  'input',
-  'destructive',
-  'surface', // bare — the real page surface is `surface-base`
-  'muted-foreground',
-  'accent-foreground',
-  'card-foreground',
-  'popover-foreground',
-  'primary-foreground',
-  'secondary-foreground',
-  'destructive-foreground'
-]);
-
-/**
- * Cores that are commonly hallucinated and have a known correct replacement.
- * Drives a precise fix hint instead of a generic "unknown token".
- */
-export const KNOWN_BAD_NAMESPACES: Record<string, string> = {
-  // `status-*` is the most frequent invention observed. Map to feedback/intents.
-  'status-':
-    'Use a `feedback-*` token (feedback-success, feedback-error, …) or a bare intent (`success`, `danger`).',
-  // `-fg` / `-foreground` suffixes are invented; the system uses `text-on-primary` etc.
-  '-fg': 'Use `text-on-primary` / `text-on-surface` for foreground-on-intent text.'
-};
-
-export { INTENT_NAMES, INTENT_VARIANTS, SCALE_STEPS };

package/src/design-linter/types.ts

@@ -1,66 +0,0 @@
-/**
- * Types for the Urbicon UI design linter.
- *
- * The linter turns the prose Anti-Patterns and Design-Quality guidance (served
- * today by `get_design_principles`, `suggest_implementation`,
- * `get_implementation_checklist`) into executable checks. Deterministic rules
- * produce `error`/`warning` findings; distribution heuristics produce `info`
- * findings. See design-linter/README context in docs/DESIGN-MCP.md.
- */
-
-/** How serious a finding is. Drives the score deduction and the report grouping. */
-export type Severity = 'error' | 'warning' | 'info';
-
-/**
- * Whether a finding comes from a deterministic rule (regex/string match — a fact
- * about the code) or a statistical heuristic (a distribution judgement that can
- * have false positives). Surfaced in the report so consumers can weight them.
- */
-export type FindingKind = 'deterministic' | 'heuristic';
-
-/** A single linter finding, anchored to a location when one exists. */
-export interface Finding {
-  /** Stable rule identifier, e.g. `raw-tailwind-color`. Used for tests and suppression. */
-  ruleId: string;
-  severity: Severity;
-  kind: FindingKind;
-  /** Human-readable description of what is wrong. */
-  message: string;
-  /** Concrete fix hint — what to do instead. */
-  fix: string;
-  /** 1-based line number, when the finding is anchored to one. */
-  line?: number;
-  /** The offending snippet (e.g. the class token), when applicable. */
-  match?: string;
-}
-
-/** A deterministic rule: scans the source and emits findings. */
-export interface Rule {
-  id: string;
-  severity: Severity;
-  /** One-line description of what the rule enforces, shown in `validate_design` rule listings. */
-  description: string;
-  /**
-   * Run the rule over the already-prepared source lines.
-   * @param lines source split by `\n`, with comments masked (see linter.ts)
-   * @param raw the original source (for rules that need cross-line context)
-   */
-  check(lines: string[], raw: string): Finding[];
-}
-
-/** Aggregate result of linting one code unit. */
-export interface LintReport {
-  findings: Finding[];
-  /** Deterministic 0–100 design-quality score. 100 = no findings. */
-  score: number;
-  counts: { error: number; warning: number; info: number };
-  /** Optional label (e.g. filename) echoed back in the report. */
-  filename?: string;
-}
-
-/** Options for a lint run. */
-export interface LintOptions {
-  filename?: string;
-  /** Skip the distribution heuristics (the `info`-level checks). Default: false. */
-  skipHeuristics?: boolean;
-}

package/src/design-manifest/index.ts

@@ -1,20 +0,0 @@
-/**
- * Public API of the design-manifest module — the persistent design-intent layer
- * (docs/DESIGN-MCP.md, Option C). Consumed by the `get_design_context`,
- * `record_design_decision`, and `sync_design_manifest` MCP tools.
- */
-
-export {
-  appendDecision,
-  createManifestTemplate,
-  DECISIONS_HEADING,
-  emptyManifest,
-  formatContext,
-  parseFrontmatter,
-  parseManifest,
-  renderDecision,
-  USAGES_HEADING,
-  upsertUsagesSection
-} from './manifest.js';
-export { scanMarkers } from './scan.js';
-export type { DesignDecision, DesignManifest, PatternUsage } from './types.js';

package/src/design-manifest/manifest.test.ts

@@ -1,175 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  appendDecision,
-  createManifestTemplate,
-  formatContext,
-  parseFrontmatter,
-  parseManifest,
-  upsertUsagesSection
-} from './manifest.js';
-import type { DesignDecision } from './types.js';
-
-describe('parseFrontmatter', () => {
-  it('reads flat key:value pairs and strips the block from the body', () => {
-    const { data, body } = parseFrontmatter(
-      '---\nparadigm: corporate\ntheme: "ocean"\n---\n# Title\nrest'
-    );
-    expect(data).toEqual({ paradigm: 'corporate', theme: 'ocean' });
-    expect(body).toBe('# Title\nrest');
-  });
-  it('returns empty data when there is no frontmatter', () => {
-    const { data, body } = parseFrontmatter('# No frontmatter');
-    expect(data).toEqual({});
-    expect(body).toBe('# No frontmatter');
-  });
-});
-
-describe('manifest template + parse round-trip', () => {
-  const template = createManifestTemplate({
-    paradigm: 'corporate',
-    theme: 'ocean',
-    projectName: 'Acme'
-  });
-
-  it('parses its own scaffold', () => {
-    const m = parseManifest(template);
-    expect(m.frontmatter.paradigm).toBe('corporate');
-    expect(m.frontmatter.theme).toBe('ocean');
-    expect(m.usages).toEqual([]);
-    expect(m.decisions).toEqual([]);
-    expect(m.exists).toBe(true);
-  });
-});
-
-describe('upsertUsagesSection', () => {
-  const template = createManifestTemplate({});
-  const usages = [
-    { pattern: 'dashboard', file: 'src/routes/dashboard/+page.svelte' },
-    { pattern: 'form-page', file: 'src/routes/signup/+page.svelte' }
-  ];
-
-  it('fills the generated block and is re-parseable', () => {
-    const updated = upsertUsagesSection(template, usages);
-    const m = parseManifest(updated);
-    expect(m.usages).toHaveLength(2);
-    expect(m.usages).toContainEqual({
-      pattern: 'dashboard',
-      file: 'src/routes/dashboard/+page.svelte'
-    });
-  });
-
-  it('is idempotent — replacing the block, not appending', () => {
-    const once = upsertUsagesSection(template, usages);
-    const twice = upsertUsagesSection(once, usages);
-    expect(twice).toBe(once);
-  });
-
-  it('removes stale usages on the next sync', () => {
-    const withTwo = upsertUsagesSection(template, usages);
-    const withOne = upsertUsagesSection(withTwo, [usages[0]!]);
-    expect(parseManifest(withOne).usages).toHaveLength(1);
-  });
-
-  it('appends a Pattern Usages section when none exists', () => {
-    const bare = '# Bare manifest\n\nsome prose\n';
-    const updated = upsertUsagesSection(bare, usages);
-    expect(updated).toContain('## Pattern Usages');
-    expect(parseManifest(updated).usages).toHaveLength(2);
-    expect(updated).toContain('some prose'); // original content preserved
-  });
-});
-
-describe('appendDecision', () => {
-  const dec = (title: string, date: string): DesignDecision => ({
-    date,
-    title,
-    status: 'accepted',
-    decision: `do ${title}`,
-    rationale: `because ${title}`
-  });
-
-  it('adds a decision into the existing section, newest first', () => {
-    const t = createManifestTemplate({});
-    const one = appendDecision(t, dec('first', '2026-06-01'));
-    const two = appendDecision(one, dec('second', '2026-06-02'));
-    const m = parseManifest(two);
-    expect(m.decisions.map((d) => d.title)).toEqual(['second', 'first']);
-    expect(m.decisions[0]!.rationale).toBe('because second');
-  });
-
-  it('creates the section when absent and preserves frontmatter + usages', () => {
-    const withUsage = upsertUsagesSection(createManifestTemplate({ paradigm: 'brutalist' }), [
-      { pattern: 'dashboard', file: 'a.svelte' }
-    ]);
-    const updated = appendDecision(withUsage, dec('x', '2026-06-13'));
-    const m = parseManifest(updated);
-    expect(m.frontmatter.paradigm).toBe('brutalist');
-    expect(m.usages).toHaveLength(1);
-    expect(m.decisions).toHaveLength(1);
-  });
-});
-
-describe('formatContext', () => {
-  it('summarises intake, usages and decisions', () => {
-    let content = createManifestTemplate({ paradigm: 'corporate', theme: 'ocean' });
-    content = upsertUsagesSection(content, [{ pattern: 'dashboard', file: 'a.svelte' }]);
-    content = appendDecision(content, {
-      date: '2026-06-13',
-      title: 'Tabs for settings',
-      status: 'accepted',
-      decision: 'use tabs'
-    });
-    const out = formatContext(parseManifest(content));
-    expect(out).toContain('corporate');
-    expect(out).toContain('`dashboard`');
-    expect(out).toContain('Tabs for settings');
-  });
-
-  it('guides the user when the manifest is empty', () => {
-    const out = formatContext(parseManifest(createManifestTemplate({})));
-    expect(out).toContain('data-design-pattern');
-    expect(out).toContain('record_design_decision');
-  });
-});
-
-describe('review hardening', () => {
-  it('does not interpret `$` sequences in a file path as replacement patterns', () => {
-    // Heading present, no marker block yet → the String.replace fallback branch.
-    const bare = '# M\n\n## Pattern Usages\n';
-    const updated = upsertUsagesSection(bare, [
-      { pattern: 'dashboard', file: "src/o'$&-$1/+page.svelte" }
-    ]);
-    expect(updated).toContain("src/o'$&-$1/+page.svelte");
-    expect(parseManifest(updated).usages[0]?.file).toBe("src/o'$&-$1/+page.svelte");
-  });
-
-  it('replaces an orphaned start marker (lost end marker) without duplicating usages', () => {
-    const orphaned =
-      '## Pattern Usages\n\n<!-- AUTO-GENERATED pattern usages — managed by sync_design_manifest; do not edit by hand -->\n\n- `dashboard` — old.svelte\n\n## Design Decisions\n';
-    const updated = upsertUsagesSection(orphaned, [{ pattern: 'form-page', file: 'new.svelte' }]);
-    const usages = parseManifest(updated).usages;
-    expect(usages).toHaveLength(1);
-    expect(usages[0]).toEqual({ pattern: 'form-page', file: 'new.svelte' });
-    expect(updated).toContain('## Design Decisions'); // following section preserved
-  });
-
-  it('collapses multi-line decision/rationale text to a single line (no truncation on re-parse)', () => {
-    const updated = appendDecision(createManifestTemplate({}), {
-      date: '2026-06-13',
-      title: 'Cache strategy',
-      status: 'accepted',
-      decision: 'Use SWR.\nFallback to stale for 30s.',
-      rationale: 'Line one.\r\nLine two.'
-    });
-    const d = parseManifest(updated).decisions[0]!;
-    expect(d.decision).toBe('Use SWR. Fallback to stale for 30s.');
-    expect(d.rationale).toBe('Line one. Line two.');
-  });
-
-  it('tolerates CRLF frontmatter', () => {
-    const { data } = parseFrontmatter(
-      '---\r\nparadigm: brutalist\r\ntheme: forest\r\n---\r\n# Title'
-    );
-    expect(data).toEqual({ paradigm: 'brutalist', theme: 'forest' });
-  });
-});