@sourcescape/ds-cli 0.3.0 → 0.4.0

package/dist/cli.js

@@ -696,14 +696,14 @@ async function commandRender(system, fileArg, flags) {
   console.log(`Preview server running at ${server.url}`);
   console.log(`Opening in browser... (Ctrl+C to stop)`);
   openInBrowser(server.url);
-  await new Promise((resolve2) => {
+  await new Promise((resolve3) => {
     process.on("SIGINT", () => {
       server.stop();
-      resolve2();
+      resolve3();
     });
     process.on("SIGTERM", () => {
       server.stop();
-      resolve2();
+      resolve3();
     });
   });
   return 0;
@@ -737,6 +737,317 @@ function openInBrowser(target) {
   exec(`${cmd} "${target}"`);
 }
 
+// src/commands/health.ts
+import { readFileSync as readFileSync6, existsSync as existsSync6, readdirSync as readdirSync3 } from "fs";
+import { join as join5 } from "path";
+function pass(label) {
+  return { label, passed: true };
+}
+function fail(label, detail) {
+  return { label, passed: false, detail };
+}
+function commandHealth(system) {
+  if (!systemExists(system)) {
+    const suggestions = listSystems().filter(
+      (s) => s.includes(system) || system.includes(s)
+    );
+    error(`Design system "${system}" not found`, suggestions);
+    return 1;
+  }
+  const sysDir = systemDir(system);
+  const results = [];
+  heading("Folder \u2194 Tag consistency");
+  for (const kind of ["molecules", "cells"]) {
+    const kindDir = join5(sysDir, "components", kind);
+    if (!existsSync6(kindDir)) continue;
+    for (const d of readdirSync3(kindDir, { withFileTypes: true })) {
+      if (!d.isDirectory()) continue;
+      const compDir = join5(kindDir, d.name);
+      const json = readComponentJson(compDir);
+      if (!json?.tag) {
+        results.push(fail(
+          `${kind}/${d.name}: tag`,
+          "missing tag in description.json"
+        ));
+        continue;
+      }
+      const tagName = json.tag.replace(/^<|>$/g, "");
+      if (tagName !== d.name) {
+        results.push(fail(
+          `${kind}/${d.name}: tag`,
+          `folder "${d.name}" \u2260 tag "${tagName}"`
+        ));
+      } else {
+        results.push(pass(`${kind}/${d.name}: tag`));
+      }
+    }
+  }
+  heading("Required files");
+  for (const kind of ["molecules", "cells"]) {
+    const kindDir = join5(sysDir, "components", kind);
+    if (!existsSync6(kindDir)) continue;
+    for (const d of readdirSync3(kindDir, { withFileTypes: true })) {
+      if (!d.isDirectory()) continue;
+      const compDir = join5(kindDir, d.name);
+      if (!existsSync6(join5(compDir, "description.json"))) {
+        results.push(fail(`${kind}/${d.name}: description.json`, "missing"));
+      } else {
+        results.push(pass(`${kind}/${d.name}: description.json`));
+      }
+      if (!existsSync6(join5(compDir, "style.css"))) {
+        results.push(fail(`${kind}/${d.name}: style.css`, "missing"));
+      } else {
+        results.push(pass(`${kind}/${d.name}: style.css`));
+      }
+    }
+  }
+  heading("description.json completeness");
+  for (const kind of ["molecules", "cells"]) {
+    const kindDir = join5(sysDir, "components", kind);
+    if (!existsSync6(kindDir)) continue;
+    for (const d of readdirSync3(kindDir, { withFileTypes: true })) {
+      if (!d.isDirectory()) continue;
+      const compDir = join5(kindDir, d.name);
+      const json = readComponentJson(compDir);
+      if (!json) continue;
+      for (const field of ["description", "tag", "example"]) {
+        const val = json[field];
+        if (!val || typeof val === "string" && val.trim() === "") {
+          results.push(fail(
+            `${kind}/${d.name}: ${field}`,
+            `empty or missing "${field}" field`
+          ));
+        } else {
+          results.push(pass(`${kind}/${d.name}: ${field}`));
+        }
+      }
+    }
+  }
+  heading("index.js imports");
+  const indexPath2 = join5(sysDir, "src", "index.js");
+  if (!existsSync6(indexPath2)) {
+    results.push(fail("src/index.js", "file not found"));
+  } else {
+    const indexSrc = readFileSync6(indexPath2, "utf-8");
+    const importPaths = [...indexSrc.matchAll(/import\s+['"]([^'"]+)['"]/g)].map(
+      (m) => m[1]
+    );
+    for (const imp of importPaths) {
+      const resolved = join5(sysDir, "src", imp);
+      if (!existsSync6(resolved)) {
+        results.push(fail(`import: ${imp}`, "file not found"));
+      } else {
+        results.push(pass(`import: ${imp}`));
+      }
+    }
+    for (const kind of ["molecules", "cells"]) {
+      const kindDir = join5(sysDir, "components", kind);
+      if (!existsSync6(kindDir)) continue;
+      for (const d of readdirSync3(kindDir, { withFileTypes: true })) {
+        if (!d.isDirectory()) continue;
+        const jsPath = join5(kindDir, d.name, "component.js");
+        if (!existsSync6(jsPath)) continue;
+        const expectedFragment = `components/${kind}/${d.name}/component.js`;
+        const imported = importPaths.some((p) => p.includes(expectedFragment));
+        if (!imported) {
+          results.push(fail(
+            `${kind}/${d.name}: import`,
+            `component.js exists but not imported in index.js`
+          ));
+        } else {
+          results.push(pass(`${kind}/${d.name}: import`));
+        }
+      }
+    }
+  }
+  heading("Token files");
+  const tokensDir = join5(sysDir, "tokens");
+  for (const required of ["colors.json", "effects.json", "layout.json"]) {
+    if (!existsSync6(join5(tokensDir, required))) {
+      results.push(fail(`tokens/${required}`, "missing"));
+    } else {
+      results.push(pass(`tokens/${required}`));
+    }
+  }
+  heading("Assets");
+  const fontsDir = join5(sysDir, "assets", "fonts");
+  if (!existsSync6(fontsDir)) {
+    results.push(fail("assets/fonts", "directory not found"));
+  } else {
+    const fontFamilies = readdirSync3(fontsDir, { withFileTypes: true }).filter(
+      (d) => d.isDirectory()
+    );
+    if (fontFamilies.length === 0) {
+      results.push(fail("assets/fonts", "no font family directories"));
+    } else {
+      let hasWoff2 = false;
+      for (const fam of fontFamilies) {
+        const files = readdirSync3(join5(fontsDir, fam.name));
+        if (files.some((f) => f.endsWith(".woff2"))) hasWoff2 = true;
+      }
+      if (!hasWoff2) {
+        results.push(fail("assets/fonts", "no .woff2 files found"));
+      } else {
+        results.push(pass("assets/fonts"));
+      }
+    }
+  }
+  const passed = results.filter((r) => r.passed).length;
+  const failed = results.filter((r) => !r.passed).length;
+  if (failed > 0) {
+    heading("Failures");
+    for (const r of results) {
+      if (!r.passed) {
+        console.log(`  FAIL  ${r.label}  \u2014  ${r.detail}`);
+      }
+    }
+  }
+  console.log();
+  console.log(
+    `${passed} passed, ${failed} failed`
+  );
+  return failed > 0 ? 1 : 0;
+}
+
+// src/commands/check.ts
+import { readFileSync as readFileSync7, existsSync as existsSync7 } from "fs";
+import { resolve as resolve2 } from "path";
+function pass2(label) {
+  return { label, passed: true };
+}
+function fail2(label, detail) {
+  return { label, passed: false, detail };
+}
+async function readStdin2() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+function extractCustomElements(markup) {
+  const results = [];
+  const lines = markup.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const lineText = lines[i];
+    for (const m of lineText.matchAll(/<([a-z][a-z0-9]*-[a-z0-9-]*)([^>]*)/g)) {
+      results.push({
+        tag: m[1],
+        line: i + 1,
+        attrs: m[2]
+      });
+    }
+  }
+  return results;
+}
+function checkAttributes(registry, elements) {
+  const results = [];
+  for (const el of elements) {
+    const entry = registry.tagMap.get(el.tag);
+    if (!entry) continue;
+    for (const m of el.attrs.matchAll(/(\w+)=""/g)) {
+      results.push(fail2(
+        `line ${el.line}: <${el.tag}>`,
+        `empty attribute "${m[1]}"`
+      ));
+    }
+  }
+  return results;
+}
+async function commandCheck(system, fileArg) {
+  if (!systemExists(system)) {
+    const suggestions = listSystems().filter(
+      (s) => s.includes(system) || system.includes(s)
+    );
+    error(`Design system "${system}" not found`, suggestions);
+    return 1;
+  }
+  if (!fileArg) {
+    error("Usage: ds <system> check <file|->", [
+      "ds fw-prd check page.xml",
+      "cat page.xml | ds fw-prd check -"
+    ]);
+    return 1;
+  }
+  let markup;
+  let fileName;
+  if (fileArg === "-") {
+    markup = await readStdin2();
+    fileName = "<stdin>";
+  } else {
+    const filePath = resolve2(fileArg);
+    if (!existsSync7(filePath)) {
+      error(`File not found: ${filePath}`);
+      return 1;
+    }
+    markup = readFileSync7(filePath, "utf-8");
+    fileName = fileArg;
+  }
+  const results = [];
+  heading(`Checking ${fileName}`);
+  const registry = buildRegistry(system);
+  const deps = resolveMarkup(registry, markup);
+  const elements = extractCustomElements(markup);
+  const uniqueTags = new Set(elements.map((e) => e.tag));
+  console.log(`  ${uniqueTags.size} unique custom elements found`);
+  console.log(`  ${elements.length} total usages
+`);
+  heading("Tag resolution");
+  for (const tag of uniqueTags) {
+    if (registry.tagMap.has(tag)) {
+      const entry = registry.tagMap.get(tag);
+      results.push(pass2(`<${tag}> \u2192 ${entry.kind}/${entry.name}`));
+    } else {
+      const lines = elements.filter((e) => e.tag === tag).map((e) => e.line);
+      results.push(fail2(
+        `<${tag}>`,
+        `unknown element (lines: ${lines.join(", ")})`
+      ));
+    }
+  }
+  heading("Dependencies");
+  const matchedCount = uniqueTags.size - deps.unmatchedTags.length;
+  console.log(`  ${deps.cssFiles.length} CSS files needed`);
+  console.log(`  ${deps.jsFiles.length} JS files needed`);
+  for (const f of [...deps.cssFiles, ...deps.jsFiles]) {
+    if (!existsSync7(f)) {
+      results.push(fail2(`dependency: ${f}`, "file not found"));
+    }
+  }
+  heading("Attributes");
+  const attrResults = checkAttributes(registry, elements);
+  results.push(...attrResults);
+  if (attrResults.length === 0) {
+    console.log("  No attribute issues found");
+  }
+  heading("Structure");
+  for (const tag of uniqueTags) {
+    const opens = (markup.match(new RegExp(`<${tag}[\\s>]`, "g")) || []).length;
+    const closes = (markup.match(new RegExp(`</${tag}>`, "g")) || []).length;
+    const selfClosing = (markup.match(new RegExp(`<${tag}[^>]*/\\s*>`, "g")) || []).length;
+    const expectedCloses = opens - selfClosing;
+    if (expectedCloses > 0 && closes < expectedCloses) {
+      results.push(fail2(
+        `<${tag}>`,
+        `${opens} opens, ${closes} closes (${expectedCloses - closes} unclosed)`
+      ));
+    } else {
+      results.push(pass2(`<${tag}>: balanced`));
+    }
+  }
+  const passed = results.filter((r) => r.passed).length;
+  const failed = results.filter((r) => !r.passed).length;
+  if (failed > 0) {
+    heading("Failures");
+    for (const r of results) {
+      if (!r.passed) {
+        console.log(`  FAIL  ${r.label}  \u2014  ${r.detail}`);
+      }
+    }
+  }
+  console.log();
+  console.log(`${passed} passed, ${failed} failed`);
+  return failed > 0 ? 1 : 0;
+}
+
 // src/cli.ts
 function showHelp() {
   console.log(`
@@ -754,6 +1065,9 @@ Usage:
   design-system <system> references <file>        Display reference file
   design-system <system> render <file>            Render markup with resolved deps
   design-system <system> render -                 Render from stdin
+  design-system <system> health                   Check design system consistency
+  design-system <system> check <file>             Validate markup against design system
+  design-system <system> check -                  Validate from stdin
 
 Flags:
   --html       Dump raw HTML to stdout
@@ -796,6 +1110,12 @@ async function main() {
   if (rest[0] === "render") {
     process.exit(await commandRender(first, rest.slice(1).join(" "), { html: values.html }));
   }
+  if (rest[0] === "health") {
+    process.exit(commandHealth(first));
+  }
+  if (rest[0] === "check") {
+    process.exit(await commandCheck(first, rest.slice(1).join(" ")));
+  }
   const flags = {
     html: values.html
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sourcescape/ds-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "CLI for browsing design system definitions",
   "license": "MIT",
@@ -11,9 +11,11 @@
     }
   },
   "bin": {
-    "design-system": "./dist/cli.js"
+    "design-system": "dist/cli.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup src/cli.ts src/index.ts --format esm --dts --clean",
     "prepublishOnly": "npm run build"