@conductor-by-89soone/tokens 0.0.0

package/dist/lint-cli.js

@@ -0,0 +1,348 @@
+import { readFileSync, statSync, readdirSync } from 'fs';
+import { join, relative, sep } from 'path';
+
+// src/build/errors.ts
+var EXIT_CODES = {
+  "TOK-CYCLE": 1,
+  "TOK-UNKNOWN-REF": 1,
+  "TOK-DEPTH": 1,
+  "TOK-TIER": 1,
+  "TOK-TIER-MISSING": 1,
+  "TOK-DUPLICATE-KEY": 1,
+  "TOK-ICON": 1,
+  "TOK-GROUP-SIZE": 1,
+  "TOK-USAGE": 1,
+  "TOK-VALUE": 1,
+  "TOK-Z-DUPLICATE": 1,
+  "TOK-PREFIX": 2,
+  "TOK-NAME-COLLISION": 2,
+  "TOK-MEDIA-VAR": 2,
+  "TOK-CP-DUPLICATE-ID": 1,
+  "TOK-CP-UNKNOWN-KEY": 1,
+  "TOK-CP-DECORATIVE": 1,
+  "TOK-CP-USAGE": 1,
+  "TOK-CP-COLOR": 1,
+  "TOK-CP-ALPHA": 1,
+  "TOK-LITERAL": 1,
+  "TOK-ARG": 3
+};
+var TokenBuildError = class extends Error {
+  code;
+  exitCode;
+  /** Indented lines printed under the summary: offending keys, cycle paths, hints. */
+  details;
+  constructor(code, summary, details = []) {
+    super(`error[${code}]: ${summary}`);
+    this.name = "TokenBuildError";
+    this.code = code;
+    this.exitCode = EXIT_CODES[code];
+    this.details = details;
+  }
+  /** The full stderr rendering, summary line first. */
+  format() {
+    return [this.message, ...this.details.map((line) => `  ${line}`)].join("\n");
+  }
+};
+
+// src/lint/source.ts
+var ALLOW_DIRECTIVE = "cdt-allow-literal";
+var ALLOW_PATTERN = new RegExp(`(?:/\\*|//)\\s*${ALLOW_DIRECTIVE}\\s*:\\s*([^*\\n]*?)\\s*(?:\\*/|$)`);
+var BLOCK_COMMENT_END = "*/";
+function blank(characters, start, end) {
+  for (let index = start; index < end; index += 1) {
+    if (characters[index] !== "\n") characters[index] = " ";
+  }
+}
+function maskComments(text) {
+  const characters = text.split("");
+  let index = 0;
+  let quote;
+  while (index < characters.length) {
+    const character = characters[index];
+    const next = characters[index + 1];
+    if (quote !== void 0) {
+      if (character === "\\") index += 2;
+      else {
+        if (character === quote) quote = void 0;
+        index += 1;
+      }
+      continue;
+    }
+    if (character === '"' || character === "'" || character === "`") {
+      quote = character;
+      index += 1;
+      continue;
+    }
+    if (character === "/" && next === "*") {
+      const end = text.indexOf(BLOCK_COMMENT_END, index + 2);
+      const stop = end === -1 ? characters.length : end + BLOCK_COMMENT_END.length;
+      blank(characters, index, stop);
+      index = stop;
+      continue;
+    }
+    if (character === "/" && next === "/") {
+      let end = index;
+      while (end < characters.length && characters[end] !== "\n") end += 1;
+      blank(characters, index, end);
+      index = end;
+      continue;
+    }
+    index += 1;
+  }
+  return characters.join("");
+}
+function headerEndLine(masked) {
+  const lines = masked.split("\n");
+  for (const [index, line] of lines.entries()) {
+    if (line.trim() !== "") return index;
+  }
+  return lines.length;
+}
+function findAllowances(file, text) {
+  const header = headerEndLine(maskComments(text));
+  return text.split("\n").flatMap((line, index) => {
+    const match = ALLOW_PATTERN.exec(line);
+    if (!match) return [];
+    const reason = match[1].trim();
+    return [
+      {
+        file,
+        line: index + 1,
+        scope: index < header ? "file" : "line",
+        reason: reason === "" ? "(no reason given)" : reason
+      }
+    ];
+  });
+}
+function isAllowed(allowances, line) {
+  return allowances.some(
+    (allowance) => allowance.scope === "file" || allowance.line === line || allowance.line === line - 1
+  );
+}
+
+// src/lint/rules.ts
+var HEX_COLOR = /#(?:[0-9a-f]{8}|[0-9a-f]{6}|[0-9a-f]{4}|[0-9a-f]{3})\b/gi;
+var FUNCTIONAL_COLOR = /\b(?:rgba?|hsla?)\([^)]*\)/gi;
+var PX_LITERAL = /(?<![\w#.])(\d+(?:\.\d+)?)px\b/g;
+var MS_LITERAL = /(?<![\w#.])(\d+(?:\.\d+)?)ms\b/g;
+var Z_INDEX = /\b(?:z-index|zIndex)\s*:\s*["'`]?\s*(-?\d+)/g;
+var FONT_SIZE_PX = /\b(?:font-size|fontSize)\s*:\s*["'`]?\s*(\d+(?:\.\d+)?px)/g;
+var MEDIA_PRELUDE = /@media[^{;]*/g;
+var DECLARATION_BLOCK = /\{[^{}]*\}/g;
+var TEXT_FAINT = "--cdt-text-faint";
+var SURFACE_ELEVATED = "--cdt-surface-elevated";
+function matchesOf(masked, pattern, rule, message) {
+  return [...masked.matchAll(pattern)].map((match) => {
+    const whole = match[0];
+    return {
+      index: match.index,
+      length: whole.length,
+      rule,
+      message: message(match[1] ?? whole),
+      snippet: whole
+    };
+  });
+}
+function mediaRanges(masked) {
+  return [...masked.matchAll(MEDIA_PRELUDE)].map((match) => [
+    match.index,
+    match.index + match[0].length
+  ]);
+}
+var within = (ranges, index) => ranges.some(([start, end]) => index >= start && index < end);
+function colorMatches(masked) {
+  return [
+    ...matchesOf(
+      masked,
+      FUNCTIONAL_COLOR,
+      "color-literal",
+      (captured) => `colour literal \`${captured}\``
+    ),
+    ...matchesOf(masked, HEX_COLOR, "color-literal", (captured) => `colour literal \`${captured}\``)
+  ];
+}
+function sizeMatches(masked) {
+  const fontSizes = matchesOf(
+    masked,
+    FONT_SIZE_PX,
+    "font-size-px",
+    (captured) => `\`font-size\` literal \`${captured}\`; use a \`--cdt-font-size-*\` token`
+  );
+  const covered = fontSizes.map((match) => [match.index, match.index + match.length]);
+  const media = mediaRanges(masked);
+  const pixels = matchesOf(
+    masked,
+    PX_LITERAL,
+    "px-literal",
+    (captured) => `px literal \`${captured}px\`; use a spacing, radius or size token`
+  ).filter((match) => !within(covered, match.index) && !within(media, match.index));
+  return [...fontSizes, ...pixels];
+}
+function faintOnElevatedMatches(masked) {
+  const violations = [];
+  for (const block of masked.matchAll(DECLARATION_BLOCK)) {
+    const body = block[0];
+    const declarations = body.split(/[;\n]/);
+    const paintsFaintText = declarations.some(
+      (declaration) => /(?:^|[\s{,"'`])(?:color|Color)\s*:/.test(declaration) && declaration.includes(TEXT_FAINT)
+    );
+    const paintsElevatedBackground = declarations.some(
+      (declaration) => /(?:^|[\s{,"'`])(?:background|background-color|backgroundColor)\s*:/.test(declaration) && declaration.includes(SURFACE_ELEVATED)
+    );
+    if (!paintsFaintText || !paintsElevatedBackground) continue;
+    const offset = body.indexOf(TEXT_FAINT);
+    violations.push({
+      index: block.index + offset,
+      length: TEXT_FAINT.length,
+      rule: "text-faint-on-elevated",
+      message: `\`${TEXT_FAINT}\` is painted on \`${SURFACE_ELEVATED}\` (2.94:1). \`text.faint\` is \`decorative\` and forbidden on that surface (FR-THM-005 AC-3)`,
+      snippet: TEXT_FAINT
+    });
+  }
+  return violations;
+}
+function zIndexMatches(masked) {
+  return matchesOf(
+    masked,
+    Z_INDEX,
+    "z-index-literal",
+    (captured) => `numeric \`z-index\` \`${captured}\`; use a \`--cdt-z-*\` token (FR-TOK-008 AC-2)`
+  );
+}
+function positionOf(text, index) {
+  const before = text.slice(0, index);
+  const line = before.split("\n").length;
+  const column = index - (before.lastIndexOf("\n") + 1) + 1;
+  return { line, column };
+}
+function lintSource(file, text) {
+  const masked = maskComments(text);
+  const matches = [
+    ...colorMatches(masked),
+    ...sizeMatches(masked),
+    ...matchesOf(
+      masked,
+      MS_LITERAL,
+      "ms-literal",
+      (captured) => `ms literal \`${captured}ms\`; use a \`--cdt-motion-*\` token`
+    ),
+    ...zIndexMatches(masked),
+    ...faintOnElevatedMatches(masked)
+  ];
+  return matches.map(({ index, rule, message, snippet }) => ({ ...positionOf(text, index), file, rule, message, snippet })).sort((one, other) => one.line - other.line || one.column - other.column || one.rule.localeCompare(other.rule));
+}
+
+// src/lint/index.ts
+var LINTED_EXTENSIONS = [".css", ".ts", ".tsx", ".mts", ".cts"];
+var SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set(["node_modules", "dist", "coverage", ".git"]);
+function isLintable(path) {
+  return LINTED_EXTENSIONS.some((extension) => path.endsWith(extension));
+}
+function walk(directory, found) {
+  for (const entry of readdirSync(directory, { withFileTypes: true }).sort(
+    (one, other) => one.name.localeCompare(other.name)
+  )) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      if (!SKIPPED_DIRECTORIES.has(entry.name)) walk(path, found);
+    } else if (entry.isFile() && isLintable(path)) {
+      found.push(path);
+    }
+  }
+}
+function collectFiles(targets, root = process.cwd()) {
+  const found = [];
+  for (const target of targets) {
+    const absolute = join(root, target);
+    let stats;
+    try {
+      stats = statSync(absolute);
+    } catch {
+      throw new TokenBuildError("TOK-ARG", `lint target \`${target}\` does not exist`, [
+        `resolved to: ${absolute}`,
+        "hint: pass a path relative to the repository root."
+      ]);
+    }
+    if (stats.isDirectory()) walk(absolute, found);
+    else if (isLintable(absolute)) found.push(absolute);
+  }
+  return found.map((path) => relative(root, path).split(sep).join("/")).sort();
+}
+function lintTokens(targets, root = process.cwd()) {
+  const files = collectFiles(targets, root);
+  const violations = [];
+  const allowances = [];
+  for (const file of files) {
+    const text = readFileSync(join(root, file), "utf8");
+    const fileAllowances = findAllowances(file, text);
+    allowances.push(...fileAllowances);
+    violations.push(
+      ...lintSource(file, text).filter((violation) => !isAllowed(fileAllowances, violation.line))
+    );
+  }
+  return { files, violations, allowances };
+}
+function formatViolation(violation) {
+  const where = `${violation.file}:${violation.line}:${violation.column}`;
+  return `${where}  ${violation.rule}  ${violation.message}`;
+}
+function formatAllowances(allowances) {
+  const lines = [`[lint:tokens] ${allowances.length} allowance(s)`];
+  for (const allowance of allowances) {
+    lines.push(`  ${allowance.file}:${allowance.line}  scope=${allowance.scope}  reason: ${allowance.reason}`);
+  }
+  return lines;
+}
+function assertNoViolations(result) {
+  if (result.violations.length === 0) return;
+  throw new TokenBuildError(
+    "TOK-LITERAL",
+    `${result.violations.length} hardcoded value(s) outside the token source`,
+    [
+      ...result.violations.map(formatViolation),
+      "hint: read the value from a `--cdt-` custom property, or annotate the line with `/* cdt-allow-literal: <reason> */`."
+    ]
+  );
+}
+
+// src/lint-cli.ts
+var USAGE = "usage: conductor-lint-tokens <path...> [--report]";
+function parseLintArgs(argv) {
+  const targets = [];
+  let report = false;
+  for (const arg of argv) {
+    if (arg === "--report") report = true;
+    else if (arg.startsWith("--")) throw new TokenBuildError("TOK-ARG", `unrecognised argument \`${arg}\``, [USAGE]);
+    else targets.push(arg);
+  }
+  if (targets.length === 0) {
+    throw new TokenBuildError("TOK-ARG", "no lint targets given", [USAGE]);
+  }
+  return { targets, report };
+}
+function runOnce(options) {
+  const result = lintTokens(options.targets);
+  if (options.report) {
+    for (const line of formatAllowances(result.allowances)) console.log(line);
+  }
+  console.log(
+    `[lint:tokens] scanned ${result.files.length} file(s), ${result.violations.length} violation(s), ${result.allowances.length} allowance(s)`
+  );
+  assertNoViolations(result);
+  return 0;
+}
+function main(argv) {
+  try {
+    return runOnce(parseLintArgs(argv));
+  } catch (error) {
+    if (error instanceof TokenBuildError) {
+      console.error(error.format());
+      return error.exitCode;
+    }
+    console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+    return 1;
+  }
+}
+process.exitCode = main(process.argv.slice(2));
+
+export { parseLintArgs };