@webjsdev/ui 0.3.14 → 0.3.16

package/README.md

@@ -111,6 +111,13 @@ it on demand with `npx @webjsdev/ui view <name>`, which is what the pointer it
 leaves behind says too). It also self-heals the theme tokens if
 they are missing.
 
+The install runs with your project's package manager. `add` looks for a
+lockfile in the current directory and then each parent, stopping at the
+workspace root, so an app inside a monorepo uses the root's lockfile:
+`pnpm-lock.yaml` means pnpm, `yarn.lock` yarn, `bun.lock` or `bun.lockb` bun,
+`package-lock.json` npm. With no lockfile it reads `npm_config_user_agent`
+(set by `bunx`, `pnpm dlx` and friends), and falls back to npm.
+
 Resolution is LOCAL-FIRST: `init` / `add` / `list` / `view` read the registry
 that ships inside the installed `@webjsdev/ui` package, so they work with no
 network. Point at a custom registry with `--registry <url>`; `webjsui diff`
@@ -127,6 +134,7 @@ always compares against the live upstream.
 | `webjsui diff [name]` | Show diff between your local copy and the live registry |
 | `webjsui info` | Print project diagnostics |
 | `webjsui build` | (For registry authors) Compile a custom registry |
+| `webjsui lint` | Opt-in design-system linter. Reports raw palette colors, arbitrary values and classes composed over a kit helper, at the line, with a message built from your own theme tokens and helper variants. Configured by a `lint` block in `components.json`; with no block it reports nothing and exits 0. `--json` for an agent loop, `--max-warnings <n>` to pin a count. |
 
 ## Tag convention
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/ui",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "type": "module",
   "description": "The AI-first component library for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Class-helper functions for visuals, custom elements only where state matters, source-copied into your repo so you own it.",
   "bin": {

package/src/commands/add.js

@@ -10,6 +10,7 @@ import { DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
 import { isCustomElementSource } from '../registry/local.js';
 import { stripExample } from '../registry/example.js';
 import { ensureTheme } from '../utils/theme.js';
+import { detectPackageManager } from '../utils/package-manager.js';
 
 export const add = new Command()
   .name('add')
@@ -247,7 +248,7 @@ function ensureDir(d) {
 }
 
 async function installDeps(cwd, deps, dev) {
-  const manager = detectPackageManager(cwd);
+  const manager = detectAddCommand(cwd);
   const flag = dev ? '-D' : '';
   const cmd = `${manager.exec} ${manager.add} ${flag} ${deps.join(' ')}`.replace(/\s+/g, ' ').trim();
   logger.info(`${logger.dim('$')} ${cmd}`);
@@ -258,9 +259,21 @@ async function installDeps(cwd, deps, dev) {
   }
 }
 
-function detectPackageManager(cwd) {
-  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return { exec: 'pnpm', add: 'add' };
-  if (existsSync(join(cwd, 'yarn.lock'))) return { exec: 'yarn', add: 'add' };
-  if (existsSync(join(cwd, 'bun.lockb'))) return { exec: 'bun', add: 'add' };
-  return { exec: 'npm', add: 'install' };
+/** Install command per manager (`-D` marks a dev dependency for all four). */
+const ADD_COMMANDS = {
+  npm: { exec: 'npm', add: 'install' },
+  pnpm: { exec: 'pnpm', add: 'add' },
+  yarn: { exec: 'yarn', add: 'add' },
+  bun: { exec: 'bun', add: 'add' },
+};
+
+/**
+ * Resolve the install command for the project at `cwd` (#1494): the lockfile
+ * walk-up (so `bun.lock` and a workspace-root lockfile both count), then the
+ * invoking tool's user agent, then npm.
+ * @param {string} cwd
+ * @param {Record<string, string | undefined>} [env]
+ */
+export function detectAddCommand(cwd, env = process.env) {
+  return ADD_COMMANDS[detectPackageManager({ cwd, env })];
 }

package/src/commands/lint.js

@@ -0,0 +1,93 @@
+import { Command } from 'commander';
+import { getConfig } from '../utils/get-config.js';
+import { lintApp } from '../lint/index.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Run the linter and shape its report, with no printing and no exit, so the
+ * command test calls this directly. `code` is 0 or 1 only, matching `webjs
+ * check`'s posture that an agent gates on non-zero: 1 when any error-level
+ * violation exists, when the warning count exceeds `maxWarnings` (-1 is no
+ * cap), or when the command cannot run at all (no `components.json`, or a
+ * config that fails the schema).
+ *
+ * @param {{ cwd?: string, json?: boolean, maxWarnings?: number|string }} [opts]
+ * @returns {{ lines: string[], code: number, report: null | { violations: any[], summary: any, warnings: string[] } }}
+ */
+export function runLint(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const maxWarnings = Number(opts.maxWarnings ?? -1);
+  /** @type {string[]} */
+  const lines = [];
+  // A run that cannot start still answers in the requested shape, so an agent
+  // loop parsing stdout under --json receives an error document, never text.
+  const refuse = (error) => {
+    if (opts.json) {
+      lines.push(JSON.stringify({ error, violations: [], summary: { count: 0, errors: 0, warnings: 0, byRule: {} }, warnings: [], configured: false }, null, 2));
+    } else {
+      lines.push(`webjsui lint: ${error}`);
+    }
+    return { lines, code: 1, report: null };
+  };
+  if (!Number.isInteger(maxWarnings) || maxWarnings < -1) {
+    return refuse(`--max-warnings expects an integer (-1 for no cap), got ${JSON.stringify(String(opts.maxWarnings))}`);
+  }
+  let config;
+  try {
+    config = getConfig(cwd);
+  } catch (e) {
+    return refuse(`components.json is invalid: ${firstIssue(e)}`);
+  }
+  if (!config) return refuse('components.json not found (run `npx @webjsdev/ui init`)');
+
+  const { violations, warnings, configured } = lintApp(cwd, config);
+  const errors = violations.filter((v) => v.severity === 'error').length;
+  const warns = violations.length - errors;
+  /** @type {Record<string, number>} */
+  const byRule = {};
+  for (const v of violations) byRule[v.rule] = (byRule[v.rule] ?? 0) + 1;
+  const report = {
+    violations,
+    summary: { count: violations.length, errors, warnings: warns, byRule },
+    warnings,
+    configured,
+  };
+
+  if (opts.json) {
+    lines.push(JSON.stringify(report, null, 2));
+  } else if (!configured) {
+    lines.push('webjsui lint: no rules configured (add a "lint" block to components.json)');
+  } else {
+    for (const w of warnings) lines.push(`⚠ ${w}`);
+    if (violations.length === 0) {
+      lines.push('webjsui lint: all checks pass ✓');
+    } else {
+      lines.push(`webjsui lint: ${violations.length} problem(s) found (${errors} error${errors === 1 ? '' : 's'}, ${warns} warning${warns === 1 ? '' : 's'})`);
+      for (const v of violations) {
+        lines.push('');
+        lines.push(`  ${v.severity === 'error' ? '✗' : '⚠'} [${v.rule}] ${v.file}:${v.line}:${v.column}`);
+        lines.push(`    ${v.message}`);
+      }
+    }
+  }
+  const code = errors > 0 || (maxWarnings >= 0 && warns > maxWarnings) ? 1 : 0;
+  return { lines, code, report };
+}
+
+function firstIssue(e) {
+  const issue = e?.issues?.[0];
+  if (issue) return `${issue.path?.join('.') || '(root)'}: ${issue.message}`;
+  return String(e?.message ?? e);
+}
+
+export const lint = new Command()
+  .name('lint')
+  .description('Check the app against its design system (opt-in, configured in components.json)')
+  .option('-c, --cwd <cwd>', 'the working directory', process.cwd())
+  .option('--json', 'emit structured violations for an agent loop')
+  .option('--max-warnings <n>', 'fail when warnings exceed this count', '-1')
+  .action((opts) => {
+    const { lines, code } = runLint(opts);
+    for (const l of lines) logger.info(l);
+    if (code !== 0) process.exitCode = code;
+  });

package/src/index.js

@@ -9,6 +9,7 @@ import { view } from './commands/view.js';
 import { diff } from './commands/diff.js';
 import { info } from './commands/info.js';
 import { build } from './commands/build.js';
+import { lint } from './commands/lint.js';
 
 const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
 
@@ -27,6 +28,7 @@ program
   .addCommand(view)
   .addCommand(diff)
   .addCommand(info)
-  .addCommand(build);
+  .addCommand(build)
+  .addCommand(lint);
 
 program.parse();