design-contract-checker 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ogia Dormon / thedollartoolkit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# design-contract-checker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line Guard Lite: compare CSS or HTML text against **your** declared design contract and get line-level findings with stable rule IDs. Five checks, zero dependencies, no account.
+
+```bash
+npx design-contract-checker --contract design-contract.txt src/styles.css index.html
+```
+
+## What it checks
+
+| ID | Catches |
+|---|---|
+| `PPG-COLOR-001` | Literal colour outside the declared palette |
+| `PPG-TYPE-001` | Font family outside the declared type system |
+| `PPG-TYPE-002` | Font size outside the declared type scale |
+| `PPG-SPACE-001` | Spacing value outside the declared scale |
+| `PPG-RADIUS-001` | Corner radius outside the declared set |
+
+## Contract format
+
+One line per category, comma-separated values:
+
+```
+colors = #f2eee5, #18231d, #a95038
+fonts = Georgia, Arial
+font-sizes = 16px, 24px, 48px
+spacing = 8px, 16px, 24px, 48px
+radii = 0, 2px, 4px
+```
+
+## Options
+
+| Flag | Meaning |
+|---|---|
+| `--contract <file>` | Required. Path to the contract file. |
+| `--json` | Machine-readable JSON (stable rule IDs, findings per file, summary). |
+| `--help` | Usage. |
+
+## Exit codes
+
+`0` clean / `1` contract violations found / `2` usage error. CI-friendly: violations fail the run.
+
+Agent-friendly: pipe `--json` findings into your coding agent and ask it to repair each `PPG-*` finding.
+
+## Honest limitations
+
+- Text analysis only: does not execute pasted HTML, load websites or inspect computed styles.
+- Values through `var()`, `calc()`, `clamp()` and CSS keywords are skipped; verify those at the token layer.
+- Not an accessibility audit and not a design-quality judge.
+
+Full check definitions: [docs/checks.md](../docs/checks.md). Browser checker: https://pixel-perfect-system.netlify.app/guard/
+
+## The system behind it
+
+Guard Lite is the free checker of [Pixel Perfect](https://pixel-perfect-system.netlify.app/) — a design-contract toolkit (DESIGN.md, agent rules, tokens) for AI-built interfaces.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const PACK = require(path.join(__dirname, "..", "package.json"));
+const engine = require(path.join(__dirname, "..", "lib", "engine.js"));
+
+const EXIT_CLEAN = 0;
+const EXIT_FINDINGS = 1;
+const EXIT_USAGE = 2;
+
+function usage() {
+  const c = [
+    "",
+    "  " + PACK.name + " v" + PACK.version + " — Guard Lite design-contract checker",
+    "",
+    "  Usage:",
+    "    design-contract-checker --contract <file> [source files...]",
+    "    design-contract-checker --json --contract <file> [source files...]",
+    "",
+    "  Contract file format (one line per category, comma separated):",
+    "    colors = #f2eee5, #18231d, #a95038",
+    "    fonts = Georgia, Arial",
+    "    font-sizes = 16px, 24px, 48px",
+    "    spacing = 8px, 16px, 24px, 48px",
+    "    radii = 0, 2px, 4px",
+    "",
+    "  Options:",
+    "    --contract <file>  Required. Path to the declared design contract.",
+    "    --json             Print machine-readable JSON instead of text.",
+    "    -h, --help         Show this help.",
+    "",
+    "  Checks: PPG-COLOR-001 PPG-TYPE-001 PPG-TYPE-002 PPG-SPACE-001 PPG-RADIUS-001",
+    "  Text analysis only: var()/calc()/clamp() values are skipped, not resolved.",
+    "  Learn: https://pixel-perfect-system.netlify.app/guard/",
+    "",
+  ].join("\n");
+  process.stdout.write(c + "\n");
+}
+
+function fail(message, details) {
+  process.stderr.write("Error: " + message + (details ? "\n" + details : "") + "\n");
+  process.exit(EXIT_USAGE);
+}
+
+function parseArgs(argv) {
+  const out = { contractPath: null, json: false, help: false, sources: [] };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help" || arg === "help") {
+      out.help = true;
+      i += 1;
+      continue;
+    }
+    if (arg === "--json") {
+      out.json = true;
+      i += 1;
+      continue;
+    }
+    if (arg === "--contract") {
+      const next = argv[i + 1];
+      if (!next) fail("--contract requires a file path.");
+      out.contractPath = next;
+      i += 2;
+      continue;
+    }
+    if (arg.indexOf("--") === 0) fail("Unknown option: " + arg, "Run with --help.");
+    out.sources.push(arg);
+    i += 1;
+  }
+  return out;
+}
+
+function readFileChecked(fullPath, maxChars, maxBytesLabel) {
+  let text;
+  try {
+    text = fs.readFileSync(fullPath, "utf8");
+  } catch (e) {
+    fail("Cannot read " + fullPath + ": " + e.message);
+  }
+  if (text.length > maxChars) {
+    fail(fullPath + " is too large for Guard Lite (" + text.length + " chars).", maxBytesLabel);
+  }
+  return text;
+}
+
+function outputText(summary, results, total) {
+  const out = [];
+  results.forEach(function (res) {
+    out.push(res.file + ": " + res.summary.lines + " lines inspected, " +
+      res.summary.violations + " contract violations, " + res.summary.reviews + " needs review\n");
+    res.findings.forEach(function (f) {
+      out.push("[" + f.id + "] " + res.file + ":" + f.line + " " + f.property);
+      if (f.status === "Review") {
+        out.push("  REVIEW — " + f.title);
+        out.push("  Found: " + f.found + " | " + f.expected);
+      } else {
+        out.push("  VIOLATION — " + f.title);
+        const allowed = f.expected.split(", ").filter(Boolean);
+        const list = allowed.length > 8 ? allowed.slice(0, 8).join(", ") + ", …" : allowed.join(", ");
+        out.push("  Found: " + f.found + " | Allowed: " + list);
+      }
+      out.push("  Repair: " + f.repair + "\n");
+    });
+    if (res.findings.length === 0) {
+      out.push("  No outside literal values were found. This does not prove the rendered interface follows the contract — only that these five text checks saw nothing outside it.\n");
+    }
+  });
+  out.push("Summary: " + total.violations + " contract violations, " + total.reviews + " needs review.");
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+function outputJson(summary, results, total) {
+  const payload = {
+    tool: PACK.name,
+    version: PACK.version,
+    note: "Text analysis only. Values through var(), calc(), clamp() or keywords are skipped. Rule IDs are stable identifiers.",
+    summary: total,
+    results: results
+  };
+  process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    usage();
+    process.exit(EXIT_CLEAN);
+  }
+  if (!args.contractPath) fail("Missing --contract.", "Run with --help for the format.");
+  if (args.sources.length === 0) fail("No source files given.", "Pass one or more CSS, HTML or text files after --contract <file>.");
+
+  const contractText = readFileChecked(
+    path.resolve(args.contractPath),
+    engine.MAX_CONTRACT_CHARS,
+    "Limit: 12000 contract characters."
+  );
+  const contract = engine.parseContract(contractText);
+  const supplied = Object.keys(contract).filter(function (k) { return contract[k].length > 0; });
+  if (supplied.length === 0) {
+    fail("The contract format was not recognised.",
+      "Use lines like: colors = #f2eee5, #18231d (names: colors, fonts, font-sizes, spacing, radii).");
+  }
+
+  const results = [];
+  args.sources.forEach(function (sourcePath) {
+    const sourceText = readFileChecked(
+      path.resolve(sourcePath),
+      engine.MAX_SOURCE_CHARS,
+      "Limit: 100000 source characters per file."
+    );
+    const r = engine.scan(contract, sourceText);
+    results.push({
+      file: path.relative(process.cwd(), path.resolve(sourcePath)) || sourcePath,
+      summary: engine.summarize(r),
+      findings: r.findings
+    });
+  });
+
+  const total = {
+    violations: results.reduce(function (s, r) { return s + r.summary.violations; }, 0),
+    reviews: results.reduce(function (s, r) { return s + r.summary.reviews; }, 0),
+    lines: results.reduce(function (s, r) { return s + r.summary.lines; }, 0)
+  };
+
+  if (args.json) outputJson(total, results, total);
+  else outputText(total, results, total);
+
+  process.exit(total.violations > 0 ? EXIT_FINDINGS : EXIT_CLEAN);
+}
+
+main();

package/lib/engine.js

@@ -0,0 +1,265 @@
+"use strict";
+
+/**
+ * Guard Lite engine — headless extraction of the checker core from
+ * guard-lite src/guard.js. Behavior parity with the web checker:
+ * same contracts, same normalization, same five stable rule IDs,
+ * same skip conditions. No DOM, no dependencies.
+ */
+
+const MAX_CONTRACT_CHARS = 12000;
+const MAX_SOURCE_CHARS = 100000;
+
+const SAMPLE_CONTRACT = `colors = #f2eee5, #18231d, #a95038, #ffffff
+fonts = Georgia, Arial
+font-sizes = 16px, 24px, 48px
+spacing = 8px, 16px, 24px, 48px
+radii = 0, 2px, 4px`;
+
+const SAMPLE_SOURCE = `.hero {
+  color: #18231d;
+  background: #f2eee5;
+  padding: 48px 23px;
+  gap: 24px;
+}
+
+.hero h1 {
+  font-family: Georgia, serif;
+  font-size: 52px;
+}
+
+.hero .primary-action {
+  color: #ffffff;
+  background-color: #675ff0;
+  border-radius: 999px;
+  padding: 15px 24px;
+}`;
+
+const RULE_META = {
+  colors: {
+    id: "PPG-COLOR-001",
+    title: "Colour outside the declared palette",
+    repair: "Replace the literal colour with the correct named colour token. Confirm the semantic role before changing it."
+  },
+  fonts: {
+    id: "PPG-TYPE-001",
+    title: "Font family outside the declared type system",
+    repair: "Use an approved font-family token. Keep an appropriate fallback after the approved family."
+  },
+  "font-sizes": {
+    id: "PPG-TYPE-002",
+    title: "Font size outside the declared scale",
+    repair: "Map the text role to the closest approved type token. Review hierarchy before rounding the value."
+  },
+  spacing: {
+    id: "PPG-SPACE-001",
+    title: "Spacing value outside the declared scale",
+    repair: "Replace the raw spacing value with the intended spacing token. Check the surrounding rhythm at each viewport."
+  },
+  radii: {
+    id: "PPG-RADIUS-001",
+    title: "Corner radius outside the declared set",
+    repair: "Use the radius assigned to this component type. Do not replace every radius without checking component roles."
+  }
+};
+
+function cleanLine(line) {
+  return line.trim();
+}
+
+function normalizeHex(value) {
+  const v = value.toLowerCase();
+  if (/^#[0-9a-f]{3}$/.test(v)) {
+    return "#" + v.slice(1).split("").map(function (c) { return c + c; }).join("");
+  }
+  if (/^#[0-9a-f]{4}$/.test(v)) {
+    return "#" + v.slice(1).split("").map(function (c) { return c + c; }).join("");
+  }
+  return v.replace(/\s+/g, "");
+}
+
+function normalizeMeasure(value) {
+  const v = value.toLowerCase().replace(/\s+/g, "");
+  if (/^-?0+(?:\.0+)?(?:px|rem|em)?$/.test(v)) return "0";
+  return v.replace(/^(-?)\./, "$10.");
+}
+
+function normalizeFont(value) {
+  return value.trim().replace(/^['"]|['"]$/g, "").toLowerCase();
+}
+
+function splitContractValues(value) {
+  const values = [];
+  let current = "";
+  let depth = 0;
+  let quote = "";
+  for (let i = 0; i < value.length; i += 1) {
+    const char = value[i];
+    if (quote) {
+      current += char;
+      if (char === quote && value[i - 1] !== "\\") quote = "";
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      current += char;
+    } else if (char === "(") {
+      depth += 1;
+      current += char;
+    } else if (char === ")") {
+      depth = Math.max(0, depth - 1);
+      current += char;
+    } else if (char === "," && depth === 0) {
+      if (current.trim()) values.push(current.trim());
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  if (current.trim()) values.push(current.trim());
+  return values;
+}
+
+function parseContract(text) {
+  const contract = { colors: [], fonts: [], "font-sizes": [], spacing: [], radii: [] };
+  text.split(/\r?\n/).forEach(function (rawLine) {
+    const line = cleanLine(rawLine);
+    if (!line) return;
+    const match = line.match(/^\s*(colors?|fonts?|font-sizes?|type-sizes?|spacing|radii|radius)\s*[:=]\s*(.+)$/i);
+    if (!match) return;
+    let category = match[1].toLowerCase();
+    if (category === "color") category = "colors";
+    if (category === "font") category = "fonts";
+    if (category === "font-size" || category === "type-size" || category === "type-sizes") category = "font-sizes";
+    if (category === "radius") category = "radii";
+    contract[category] = contract[category].concat(splitContractValues(match[2]));
+  });
+
+  contract.colors = contract.colors.map(normalizeHex);
+  contract.fonts = contract.fonts.map(normalizeFont);
+  contract["font-sizes"] = contract["font-sizes"].map(normalizeMeasure);
+  contract.spacing = contract.spacing.map(normalizeMeasure);
+  contract.radii = contract.radii.map(normalizeMeasure);
+  return contract;
+}
+
+function inertSource(text) {
+  return text
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, function (block) { return block.replace(/[^\n]/g, " "); })
+    .replace(/\/\*[\s\S]*?\*\//g, function (block) { return block.replace(/[^\n]/g, " "); });
+}
+
+function declarationValues(line, propertyPattern) {
+  const values = [];
+  const valuePattern = "((?:\\\"[^\\\"\\n]*\\\"|'[^'\\n]*'|[^;}\\\"'\\n])+)";
+  const re = new RegExp("(?:^|[;{\\s\\\"])(" + propertyPattern + ")\\s*:\\s*" + valuePattern, "gi");
+  let match;
+  while ((match = re.exec(line)) !== null) {
+    values.push({ property: match[1].toLowerCase(), value: match[2].trim() });
+  }
+  return values;
+}
+
+function skipExpression(value) {
+  return /\b(?:var|calc|clamp|min|max)\s*\(/i.test(value);
+}
+
+function addFinding(list, seen, category, status, line, property, found, expected) {
+  const meta = RULE_META[category];
+  const key = [meta.id, status, line, property, found].join("|");
+  if (seen.has(key)) return;
+  seen.add(key);
+  list.push({
+    category: category,
+    id: meta.id,
+    title: meta.title,
+    status: status,
+    line: line,
+    property: property,
+    found: found,
+    expected: expected,
+    repair: meta.repair
+  });
+}
+
+function compareValue(list, seen, contract, category, lineNumber, property, rawValue, normalized) {
+  const allowed = contract[category] || [];
+  if (allowed.length === 0) {
+    addFinding(list, seen, category, "Review", lineNumber, property, rawValue, "No approved values were supplied for this category.");
+    return;
+  }
+  if (!allowed.includes(normalized)) {
+    addFinding(list, seen, category, "Violation", lineNumber, property, rawValue, allowed.join(", "));
+  }
+}
+
+function scan(contract, source) {
+  const findings = [];
+  const seen = new Set();
+  const lines = inertSource(source).split(/\r?\n/);
+
+  lines.forEach(function (line, index) {
+    const lineNumber = index + 1;
+
+    declarationValues(line, "color|background|background-color|border(?:-(?:top|right|bottom|left|inline(?:-start|-end)?|block(?:-start|-end)?))?(?:-color)?|outline-color|fill|stroke").forEach(function (decl) {
+      if (skipExpression(decl.value)) return;
+      const matches = decl.value.match(/#[0-9a-f]{3,8}\b|(?:rgb|hsl)a?\([^)]*\)/gi) || [];
+      matches.forEach(function (value) {
+        compareValue(findings, seen, contract, "colors", lineNumber, decl.property, value, normalizeHex(value));
+      });
+    });
+
+    declarationValues(line, "font-family").forEach(function (decl) {
+      if (skipExpression(decl.value)) return;
+      const firstFamily = decl.value.split(",")[0].trim();
+      compareValue(findings, seen, contract, "fonts", lineNumber, decl.property, firstFamily, normalizeFont(firstFamily));
+    });
+
+    declarationValues(line, "font-size").forEach(function (decl) {
+      if (skipExpression(decl.value)) return;
+      const values = decl.value.match(/-?(?:\d+\.?\d*|\.\d+)(?:px|rem|em)\b/gi) || [];
+      values.forEach(function (value) {
+        compareValue(findings, seen, contract, "font-sizes", lineNumber, decl.property, value, normalizeMeasure(value));
+      });
+    });
+
+    declarationValues(line, "margin(?:-[a-z]+)?|padding(?:-[a-z]+)?|gap|row-gap|column-gap").forEach(function (decl) {
+      if (skipExpression(decl.value)) return;
+      const values = decl.value.match(/-?(?:\d+\.?\d*|\.\d+)(?:px|rem|em)\b|(?:^|\s)0(?=\s|$)/gi) || [];
+      values.forEach(function (value) {
+        const clean = value.trim();
+        compareValue(findings, seen, contract, "spacing", lineNumber, decl.property, clean, normalizeMeasure(clean));
+      });
+    });
+
+    declarationValues(line, "border-radius|border-(?:top|bottom)-(?:left|right)-radius").forEach(function (decl) {
+      if (skipExpression(decl.value)) return;
+      const values = decl.value.match(/(?:\d+\.?\d*|\.\d+)(?:px|rem|em)\b|(?:^|\s)0(?=\s|$)/gi) || [];
+      values.forEach(function (value) {
+        const clean = value.trim();
+        compareValue(findings, seen, contract, "radii", lineNumber, decl.property, clean, normalizeMeasure(clean));
+      });
+    });
+  });
+
+  return { findings: findings, lines: lines.length };
+}
+
+function summarize(result) {
+  return {
+    violations: result.findings.filter(function (f) { return f.status === "Violation"; }).length,
+    reviews: result.findings.filter(function (f) { return f.status === "Review"; }).length,
+    lines: result.lines
+  };
+}
+
+module.exports = {
+  MAX_CONTRACT_CHARS: MAX_CONTRACT_CHARS,
+  MAX_SOURCE_CHARS: MAX_SOURCE_CHARS,
+  SAMPLE_CONTRACT: SAMPLE_CONTRACT,
+  SAMPLE_SOURCE: SAMPLE_SOURCE,
+  RULE_META: RULE_META,
+  parseContract: parseContract,
+  scan: scan,
+  summarize: summarize
+};

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "design-contract-checker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Guard Lite: check CSS or HTML text against your declared design contract (colors, fonts, font sizes, spacing, radii). Five stable checks, zero dependencies.",
+  "license": "MIT",
+  "author": "Pixel Perfect <https://pixel-perfect-system.netlify.app/>",
+  "homepage": "https://pixel-perfect-system.netlify.app/guard/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thedollartoolkit-boop/guard-lite.git",
+    "directory": "cli"
+  },
+  "bugs": "https://github.com/thedollartoolkit-boop/guard-lite/issues",
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "css",
+    "lint",
+    "linting",
+    "checker",
+    "coding-agent",
+    "ai",
+    "guard-lite",
+    "pixel-perfect"
+  ],
+  "type": "commonjs",
+  "main": "lib/engine.js",
+  "bin": {
+    "design-contract-checker": "bin/cli.js"
+  },
+  "files": [
+    "lib/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "scripts": {
+    "test": "node test/run.js"
+  }
+}