@tok124/tokcss 1.0.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@tok124/tokcss",
+  "version": "1.0.0",
+  "description": "A stupidly simple CSS preprocessor with one directive: #include:\"file.css\"; — optionally wrapped in @layer/@supports/@media, just like @import.",
+  "bin": {
+    "tokcss": "tokcss.js"
+  },
+  "main": "tokcss.js",
+  "files": [
+    "tokcss.js"
+  ],
+  "keywords": [
+    "css",
+    "preprocessor",
+    "include",
+    "cli",
+    "layer",
+    "cascade-layers"
+  ],
+  "author": "Tokdev",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  }
+}

package/tokcss.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * tokcss — a stupidly simple CSS "preprocessor"
+ *
+ * The only thing it understands is:
+ *
+ *   #include:"path/to/file.css";
+ *
+ * optionally followed by the same trailing conditions @import supports:
+ *
+ *   #include:"reset.css" layer(reset);
+ *   #include:"grid.css" supports(display: grid);
+ *   #include:"wide.css" (width >= 50rem);
+ *   #include:"a.css" layer(base) supports(display: grid) (min-width: 500px);
+ *
+ * Each one wraps the included file's compiled content in the matching
+ * @layer / @supports / @media block, nested in that order.
+ *
+ * It reads an entry .tokcss file, follows every #include, and glues
+ * everything together into one plain .css file — like SCSS's @use,
+ * but with a single directive and zero other opinions.
+ *
+ * Usage:
+ *   node tokcss.js entry.tokcss                -> prints result to stdout
+ *   node tokcss.js entry.tokcss -o out.css      -> writes result to out.css
+ *   node tokcss.js entry.tokcss -o out.css -w   -> watches all included files, recompiles on change
+ *   node tokcss.js entry.tokcss -o out.css --no-banner   -> omit the "from: ..." source markers
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const INCLUDE_RE = /#include:"([^"]+)"\s*([^;\n]*);?/g;
+
+/**
+ * Parses the text after the quoted path (e.g. `layer(reset) (width >= 50rem)`)
+ * into its layer / supports / media parts, mirroring @import's grammar.
+ * Returns null values for anything not present.
+ */
+function parseModifiers(raw) {
+  let rest = raw.trim();
+  let layer = null; // null = no layer; '' = anonymous layer; else a layer name
+  let supports = null;
+
+  let m = rest.match(/^layer\(([^)]*)\)/i);
+  if (m) {
+    layer = m[1].trim();
+    rest = rest.slice(m[0].length).trim();
+  } else if (/^layer\b/i.test(rest)) {
+    layer = '';
+    rest = rest.replace(/^layer\b/i, '').trim();
+  }
+
+  m = rest.match(/^supports\(([^)]*)\)/i);
+  if (m) {
+    supports = m[1].trim();
+    rest = rest.slice(m[0].length).trim();
+  }
+
+  // Whatever's left is the media condition, e.g. "(width >= 50rem)" or "screen and (min-width: 500px)".
+  const media = rest.trim() || null;
+
+  return { layer, supports, media };
+}
+
+/** Indents every non-blank line of `text` by `spaces` spaces. */
+function indent(text, spaces = 2) {
+  const pad = ' '.repeat(spaces);
+  return text
+    .split('\n')
+    .map((line) => (line.trim() ? pad + line : line))
+    .join('\n');
+}
+
+/** Wraps compiled content in @layer / @supports / @media blocks per the parsed modifiers. */
+function applyModifiers(content, mods) {
+  let out = content;
+  if (mods.media) out = `@media ${mods.media} {\n${indent(out)}}\n`;
+  if (mods.supports !== null) out = `@supports (${mods.supports}) {\n${indent(out)}}\n`;
+  if (mods.layer !== null) out = `@layer${mods.layer ? ' ' + mods.layer : ''} {\n${indent(out)}}\n`;
+  return out;
+}
+
+/**
+ * Recursively resolves #include statements starting from entryFile.
+ * `seen` tracks absolute paths already inlined so:
+ *   - circular includes don't infinite-loop
+ *   - the same file included twice only gets inlined once (like @use)
+ * `touched` collects every file that was actually read, so --watch
+ * knows what to keep an eye on.
+ */
+function compile(entryFile, { seen = new Set(), touched = new Set(), banner = true } = {}) {
+  const fullPath = path.resolve(entryFile);
+
+  if (seen.has(fullPath)) {
+    return banner ? `/* skipped duplicate include: ${relative(fullPath)} */\n` : '';
+  }
+  seen.add(fullPath);
+
+  if (!fs.existsSync(fullPath)) {
+    throw new Error(`#include target not found: ${fullPath}`);
+  }
+  touched.add(fullPath);
+
+  const dir = path.dirname(fullPath);
+  const raw = fs.readFileSync(fullPath, 'utf8');
+
+  const body = raw.replace(INCLUDE_RE, (match, includePath, modifierText) => {
+    const resolved = path.resolve(dir, includePath);
+    const compiled = compile(resolved, { seen, touched, banner });
+    const mods = parseModifiers(modifierText);
+    return applyModifiers(compiled, mods);
+  });
+
+  return banner ? `/* --- from: ${relative(fullPath)} --- */\n${body}\n` : body;
+}
+
+function relative(p) {
+  return path.relative(process.cwd(), p) || path.basename(p);
+}
+
+function parseArgs(argv) {
+  const args = { input: null, output: null, watch: false, banner: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-o' || a === '--output') args.output = argv[++i];
+    else if (a === '-w' || a === '--watch') args.watch = true;
+    else if (a === '--no-banner') args.banner = false;
+    else if (!args.input) args.input = a;
+  }
+  return args;
+}
+
+function run(args) {
+  const touched = new Set();
+  let result;
+  try {
+    result = compile(args.input, { touched, banner: args.banner });
+  } catch (err) {
+    console.error(`tokcss: ${err.message}`);
+    return { ok: false, touched };
+  }
+
+  if (args.output) {
+    fs.mkdirSync(path.dirname(path.resolve(args.output)), { recursive: true });
+    fs.writeFileSync(args.output, result);
+    console.log(`tokcss: compiled -> ${args.output} (${touched.size} file${touched.size === 1 ? '' : 's'})`);
+  } else {
+    process.stdout.write(result);
+  }
+  return { ok: true, touched };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.input) {
+    console.error('Usage: node tokcss.js <entry.tokcss> [-o out.css] [-w] [--no-banner]');
+    process.exit(1);
+  }
+
+  const { ok, touched } = run(args);
+
+  if (args.watch && !ok) {
+    console.error('tokcss: fix the error above, then re-run to start watching.');
+    process.exit(1);
+  }
+
+  if (args.watch) {
+    if (!args.output) {
+      console.error('tokcss: --watch requires -o <output file>');
+      process.exit(1);
+    }
+    console.log(`tokcss: watching ${touched.size} file(s) for changes... (Ctrl+C to stop)`);
+    const watchers = new Map();
+
+    const rewatch = () => {
+      // Recompute the file set after every recompile, since edits can
+      // add or remove #include lines and change what needs watching.
+      for (const w of watchers.values()) w.close();
+      watchers.clear();
+
+      const { touched: newTouched } = run(args);
+      for (const file of newTouched) {
+        const watcher = fs.watch(file, { persistent: true }, () => {
+          // Debounce-ish: editors often fire multiple events per save.
+          setTimeout(rewatch, 50);
+        });
+        watchers.set(file, watcher);
+      }
+    };
+
+    for (const file of touched) {
+      const watcher = fs.watch(file, { persistent: true }, () => {
+        setTimeout(rewatch, 50);
+      });
+      watchers.set(file, watcher);
+    }
+  }
+}
+
+main();