@nlabs/lex 2.0.3 → 2.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nlabs/lex",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Lex",
   "license": "MIT",
   "type": "module",
@@ -53,6 +53,7 @@
     "build:all": "npm run build && npm run build:ai",
     "build:ai": "NODE_ENV=production && npx swc 'src/commands/ai/**/*.{ts,tsx}' --out-dir ./lib/commands/ai --source-maps inline",
     "declarations": "tsc -p tsconfig.build.json",
+    "docs:check": "npm run build && node scripts/validate-docs.js",
     "clean": "rm -rf lib node_modules package-lock.json *.log coverage",
     "compile": "tsc -p tsconfig.build.json",
     "env": "LEX_CONFIG='{\"useTypescript\":true}'",
@@ -86,20 +87,20 @@
   "dependencies": {
     "@playwright/test": "^1.62.1",
     "@rollup/plugin-inject": "^5.0.5",
-    "@storybook/addon-docs": "^10.5.8",
-    "@storybook/addon-links": "^10.5.8",
-    "@storybook/addon-themes": "^10.5.8",
-    "@storybook/react": "^10.5.8",
-    "@storybook/react-vite": "^10.5.8",
+    "@storybook/addon-docs": "^10.5.10",
+    "@storybook/addon-links": "^10.5.10",
+    "@storybook/addon-themes": "^10.5.10",
+    "@storybook/react": "^10.5.10",
+    "@storybook/react-vite": "^10.5.10",
     "@swc/cli": "^0.8.1",
-    "@swc/core": "^1.16.0",
-    "@swc/react-compiler": "^1.16.0",
+    "@swc/core": "^1.16.1",
+    "@swc/react-compiler": "^1.16.1",
     "@tailwindcss/forms": "^0.5.11",
     "@tailwindcss/nesting": "^0.0.0-insiders.565cd3e",
     "@tailwindcss/postcss": "4.3.3",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.2",
-    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/coverage-v8": "4.1.11",
     "assert": "^2.1.0",
     "autoprefixer": "^10.5.4",
     "boxen": "8.0.1",
@@ -109,9 +110,9 @@
     "commander": "^15.0.0",
     "compare-versions": "^6.1.1",
     "core-js": "^3.50.0",
-    "cssnano": "^8.0.6",
+    "cssnano": "^8.0.8",
     "esbuild": "^0.28.2",
-    "eslint": "^10.8.1",
+    "eslint": "^10.9.0",
     "eslint-config-styleguidejs": "^5.0.7",
     "execa": "10.0.1",
     "expect": "^30.4.1",
@@ -129,7 +130,7 @@
     "luxon": "^3.7.2",
     "math-expression-evaluator": "^2.0.7",
     "npm-check-updates": "^23.0.2",
-    "openai": "^7.4.0",
+    "openai": "^7.5.0",
     "ora": "9.4.1",
     "os-browserify": "^0.3.0",
     "pacote": "^22.0.0",
@@ -156,7 +157,7 @@
     "rimraf": "^6.1.3",
     "semver": "^7.8.5",
     "sharp": "^0.35.3",
-    "storybook": "^10.5.8",
+    "storybook": "^10.5.10",
     "stream-browserify": "^3.0.0",
     "stream-http": "^3.2.0",
     "svgo": "4.0.2",
@@ -164,14 +165,14 @@
     "ts-node": "^10.9.2",
     "typescript": "^7.0.2",
     "util": "^0.12.5",
-    "vite": "^8.2.1",
-    "vitest": "^4.1.10",
+    "vite": "^8.2.2",
+    "vitest": "4.1.11",
     "vm-browserify": "^1.1.2",
     "ws": "^8.21.3"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",
-    "@types/luxon": "^3.7.4",
+    "@types/luxon": "^3.7.5",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",
     "@types/semver": "^7.8.0"

package/scripts/validate-docs.js

@@ -0,0 +1,141 @@
+import {execFileSync} from 'child_process';
+import {transformSync} from 'esbuild';
+import {existsSync, readFileSync, readdirSync, statSync} from 'fs';
+import {dirname, extname, resolve} from 'path';
+
+const root = process.cwd();
+const docs = ['README.md', 'CHANGELOG.md', 'MIGRATION_V2.md'];
+
+const collectMarkdown = (directory) => {
+  for(const entry of readdirSync(directory)) {
+    const path = resolve(directory, entry);
+    if(statSync(path).isDirectory()) {
+      collectMarkdown(path);
+    } else if(extname(path) === '.md') {
+      docs.push(path.slice(root.length + 1));
+    }
+  }
+};
+
+collectMarkdown(resolve(root, 'examples'));
+collectMarkdown(resolve(root, 'src/commands'));
+
+const rootHelp = execFileSync(process.execPath, ['lib/lex.js', '--help'], {encoding: 'utf8'});
+const commands = new Set([...rootHelp.matchAll(/^  ([\w-]+)(?:\s|$)/gm)].map((match) => match[1]));
+const commandOptions = new Map();
+const errors = [];
+const lexExports = await import('../lib/index.js');
+const documentationCommands = {
+  ai: 'ai',
+  build: 'build',
+  clean: 'clean',
+  compile: 'compile',
+  config: 'config',
+  create: 'create',
+  dev: 'dev',
+  init: 'init',
+  link: 'linked',
+  lint: 'lint',
+  migrate: 'migrate',
+  publish: 'publish',
+  'serverless-deploy': 'serverless-deploy',
+  'serverless-dev': 'serverless-dev',
+  storybook: 'storybook',
+  test: 'test',
+  update: 'update',
+  upgrade: 'upgrade',
+  versions: 'versions'
+};
+
+for(const command of commands) {
+  if(command === 'help') continue;
+  const help = execFileSync(process.execPath, ['lib/lex.js', command, '--help'], {encoding: 'utf8'});
+  commandOptions.set(command, new Set([...help.matchAll(/--[A-Za-z][\w-]*/g)].map((match) => match[0])));
+}
+
+for(const relativePath of docs) {
+  const filePath = resolve(root, relativePath);
+  const content = readFileSync(filePath, 'utf8');
+
+  for(const match of content.matchAll(/!?\[[^\]]*\]\(([^)]+)\)/g)) {
+    const target = match[1].split('#')[0].trim();
+    if(!target || /^(?:https?:|mailto:)/.test(target)) continue;
+    const decodedTarget = decodeURIComponent(target.replace(/^<|>$/g, ''));
+    if(!existsSync(resolve(dirname(filePath), decodedTarget))) {
+      errors.push(`${relativePath}: broken local link ${match[1]}`);
+    }
+  }
+
+  for(const match of content.matchAll(/```json\s*\n([\s\S]*?)```/g)) {
+    try {
+      JSON.parse(match[1]);
+    } catch(error) {
+      errors.push(`${relativePath}: invalid JSON example (${error.message})`);
+    }
+  }
+
+  for(const match of content.matchAll(/```(javascript|js|typescript|ts)\s*\n([\s\S]*?)```/g)) {
+    try {
+      transformSync(match[2], {
+        format: 'esm',
+        loader: match[1].startsWith('t') ? 'ts' : 'js',
+        target: 'es2023'
+      });
+    } catch(error) {
+      const message = error.errors?.[0]?.text || error.message;
+      errors.push(`${relativePath}: invalid ${match[1]} example (${message})`);
+    }
+  }
+
+  for(const match of content.matchAll(/import\s*\{([^}]+)\}\s*from\s*['"]@nlabs\/lex['"]/g)) {
+    const names = match[1].split(',').map((name) => name.trim().split(/\s+as\s+/)[0]);
+    for(const name of names) {
+      if(name && !(name in lexExports)) {
+        errors.push(`${relativePath}: @nlabs/lex does not export ${name}`);
+      }
+    }
+  }
+
+  if(relativePath.endsWith('.test.md')) {
+    for(const match of content.matchAll(/`([\w.-]+\.test\.[jt]sx?)`/g)) {
+      if(!existsSync(resolve(dirname(filePath), match[1]))) {
+        errors.push(`${relativePath}: referenced test file does not exist: ${match[1]}`);
+      }
+    }
+  }
+
+  const commandDirectory = relativePath.match(/^src\/commands\/([^/]+)\/[^/]+\.docs\.md$/)?.[1];
+  const documentedCommand = commandDirectory ? documentationCommands[commandDirectory] : undefined;
+  if(documentedCommand) {
+    const validOptions = commandOptions.get(documentedCommand) || new Set();
+    for(const match of content.matchAll(/(?<![\w])(--[A-Za-z][\w-]*)/g)) {
+      if(!validOptions.has(match[1])) {
+        errors.push(`${relativePath}: unknown documented option ${match[1]} for lex ${documentedCommand}`);
+      }
+    }
+  }
+
+  for(const [index, line] of content.split('\n').entries()) {
+    for(const commandMatch of line.matchAll(/\blex\s+([\w-]+)([^`|]*)/g)) {
+      const [, command, remainder] = commandMatch;
+      if(!commands.has(command)) {
+        errors.push(`${relativePath}:${index + 1}: unknown command lex ${command}`);
+        continue;
+      }
+
+      const validOptions = commandOptions.get(command) || new Set();
+      for(const option of remainder.match(/--[A-Za-z][\w-]*/g) || []) {
+        if(!validOptions.has(option)) {
+          errors.push(`${relativePath}:${index + 1}: unknown option ${option} for lex ${command}`);
+        }
+      }
+    }
+  }
+}
+
+if(errors.length > 0) {
+  console.error([...new Set(errors)].join('\n'));
+  process.exitCode = 1;
+} else {
+  console.log(`Documentation validation passed for ${docs.length} Markdown files.`);
+}