refactor: remove unnecessary comments and improve code clarity across multiple scripts

Author: minirang

scripts/check-engine.mjs

@@ -65,8 +65,6 @@ function runScript(file, cwd) {
     return { code: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", timedOut: r.error?.code === "ETIMEDOUT" };
 }
 
-// ------------------------------------------------------------ 1. code blocks
-
 function listMarkdown(dir, out = []) {
     for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
         const full = path.join(dir, e.name);
@@ -121,8 +119,6 @@ for (const file of mdFiles) {
     });
 }
 
-// --------------------------------------------------------------- 2. examples
-
 const exDir = path.join(root, "src/examples");
 for (const name of fs.readdirSync(exDir).filter((n) => /^\d+_/.test(n)).sort()) {
     const full = path.join(exDir, name);
@@ -139,8 +135,6 @@ for (const name of fs.readdirSync(exDir).filter((n) => /^\d+_/.test(n)).sort())
     if (verbose) console.log(`  ${r.code === 0 ? "ok " : "ERR"} src/examples/${name}`);
 }
 
-// --------------------------------------------- 3 + 4. names and the web policy
-
 const meta = JSON.parse(fs.readFileSync(path.join(root, "src/generated/engine-meta.json"), "utf8"));
 const known = new Set([...Object.values(meta.dlc).flatMap((d) => d.functions), ...meta.coreBuiltins]);
 // A prefix counts as "a library prefix" when at least two functions share it (math_, str_, list_ ...).
@@ -168,8 +162,6 @@ for (const name of Object.keys(policy.blockedDlcs ?? {})) {
     if (!(name in meta.dlc)) fail("src/engine/webPolicy.json", `blocks DLC "${name}", which the engine does not have (typo, or the library was removed)`);
 }
 
-// ------------------------------------------------------- 5. metadata freshness
-
 const engineDir = opt("--engine") ?? [path.join(root, "../cuffscript"), path.join(root, "../cuffscript-main"), path.dirname(cuffc)].find((d) => fs.existsSync(path.join(d, "engine")));
 let metaStatus = "not checked (no engine source found; pass --engine <dir>)";
 if (engineDir && fs.existsSync(path.join(engineDir, "engine"))) {
@@ -185,8 +177,6 @@ if (engineDir && fs.existsSync(path.join(engineDir, "engine"))) {
     }
 }
 
-// -------------------------------------------------------------------- report
-
 console.log(`cuffc: ${cuffc}`);
 console.log(`code blocks run: ${counts.run} (${counts.outputs} with output compared)   skipped (fragment/skip): ${counts.skipped}   examples run: ${counts.examples}   library names checked: ${counts.names}`);
 console.log(`engine metadata: ${metaStatus}`);

scripts/lib/content.mjs

@@ -37,6 +37,7 @@ function readJson(file, fallback) {
         throw new Error(`cannot read ${file}: ${err.message}`, { cause: err });
     }
 }
+
 function listMarkdown(dir) {
     if (!fs.existsSync(dir)) throw new Error(`content directory not found: ${dir}`);
     return fs
@@ -91,8 +92,6 @@ export function buildVars(ctx, extra = {}) {
     };
 }
 
-// ------------------------------------------------------ generated reference
-
 function code(s) {
     return `<code>${escapeText(s)}</code>`;
 }
@@ -131,8 +130,6 @@ function makeInclude(ctx) {
     return (name) => (table[name] ? table[name]() : undefined);
 }
 
-// -------------------------------------------------------------------- guide
-
 export function buildGuide(ctx) {
     const dir = path.join(ctx.root, "content/guide");
     const files = listMarkdown(dir);
@@ -196,8 +193,6 @@ function renderMarkdownInline(text, { file, vars }) {
     return r.html.replace(/^<p>([\s\S]*)<\/p>$/, "$1");
 }
 
-// --------------------------------------------------------------------- home
-
 function docsGridHtml(guide) {
     const items = guide.groups
         .filter((g) => g.showOnHome)
@@ -237,17 +232,17 @@ export function buildHome(ctx, guide) {
         if (type === "hero") {
             cards.push(
                 `<section class="home-card home-card-hero">\n` +
-                    `<a class="home-logo-link" href="/">\n<img class="home-logo" src="/favicon.svg" alt="CuffScript 로고" />\n</a>\n` +
-                    `<h1>${renderInline(title)}</h1>\n` +
-                    (data.slogan ? `<p class="home-slogan">${renderInline(String(data.slogan))}</p>\n` : "") +
-                    `${rendered}\n</section>`,
+                `<a class="home-logo-link" href="/">\n<img class="home-logo" src="/favicon.svg" alt="CuffScript 로고" />\n</a>\n` +
+                `<h1>${renderInline(title)}</h1>\n` +
+                (data.slogan ? `<p class="home-slogan">${renderInline(String(data.slogan))}</p>\n` : "") +
+                `${rendered}\n</section>`,
             );
         } else if (type === "news") {
             cards.push(
                 `<section class="home-card" id="${id}">\n<h2>${renderInline(title)}</h2>\n${rendered}\n` +
-                    `<ul class="home-news-list" id="news-list"></ul>\n` +
-                    `<p class="home-news-state" id="news-state">불러오는 중…</p>\n` +
-                    `<p class="home-news-more">\n<a href="${changelogUrl}" target="_blank" rel="noreferrer">전체 변경 이력 보기 →</a>\n</p>\n</section>`,
+                `<ul class="home-news-list" id="news-list"></ul>\n` +
+                `<p class="home-news-state" id="news-state">불러오는 중…</p>\n` +
+                `<p class="home-news-more">\n<a href="${changelogUrl}" target="_blank" rel="noreferrer">전체 변경 이력 보기 →</a>\n</p>\n</section>`,
             );
         } else if (type === "docs") {
             cards.push(`<section class="home-card" id="${id}">\n<h2>${renderInline(title)}</h2>\n${rendered}\n${docs.html}\n</section>`);
@@ -260,8 +255,6 @@ export function buildHome(ctx, guide) {
     return { tocHtml: `<div class="home-toc-group">\n<h2>이 페이지</h2>\n${toc.join("\n")}\n</div>`, cardsHtml: cards.join("\n") };
 }
 
-// --------------------------------------------------------------- html shells
-
 const PLACEHOLDERS = {
     "<!--@guide:toc-->": (b) => b.guide.tocHtml,
     "<!--@guide:article-->": (b) => b.guide.articleHtml,

scripts/lib/engine-meta.mjs

@@ -123,7 +123,6 @@ export function extractEngineMeta(engineDir) {
     const pkgPath = path.join(engineDir, "npm", "package.json");
     const engineVersion = fs.existsSync(pkgPath) ? JSON.parse(readText(pkgPath)).version : "unknown";
 
-    // ---- keywords / types / literals (lexer keyword map)
     const kw = src.find(/keywordMap\s*\(\s*\)\s*\{/, "keywordMap()");
     const kwBody = braceBody(kw.text, kw.match.index);
     const entries = [...kwBody.matchAll(/\{\s*"([^"]+)"\s*,\s*TokenType::([A-Z_]+)\s*\}/g)].map((m) => [m[1], m[2]]);
@@ -141,7 +140,6 @@ export function extractEngineMeta(engineDir) {
     const dlc = {};
     for (const name of dlcNames) dlc[name] = { functions: functionNames(src.registerBody(name)) };
 
-    // ---- always-available functions (no `use` needed)
     const core = src.find(/void\s+registerBuiltins\s*\([^)]*\)\s*\{/, "registerBuiltins()");
     const coreBody = braceBody(core.text, core.match.index);
     const coreBuiltins = functionNames(coreBody);
@@ -150,7 +148,6 @@ export function extractEngineMeta(engineDir) {
         if (dlc[lib]) coreBuiltins.push(...dlc[lib].functions);
     }
 
-    // ---- error codes
     const ec = src.find(/enum\s+class\s+ErrorCode\s*\{/, "enum class ErrorCode");
     const ecBody = braceBody(ec.text, ec.match.index);
     const errorCodes = [...ecBody.matchAll(/\b([A-Z]\w*)\s*=\s*(\d{4})\b/g)].map((m) => ({ code: `E${m[2]}`, name: m[1] }));
@@ -168,8 +165,6 @@ export function extractEngineMeta(engineDir) {
     };
 }
 
-// ------------------------------------------------------ verify against cuffc
-
 function runCuffc(cuffc, script) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cuff-probe-"));
     try {
@@ -212,8 +207,6 @@ export function verifyAgainstBinary(meta, cuffc) {
     return problems;
 }
 
-// ------------------------------------------------------------------- diffing
-
 export function describeDiff(oldMeta, newMeta) {
     const lines = [];
     const delta = (label, a, b) => {

scripts/lib/markdown.mjs

@@ -11,7 +11,7 @@
 //   - block includes {{ns:name}} and inline variables {{a.b}}
 //   - raw HTML blocks (a line starting with a tag) and a small inline-tag whitelist
 // Code is ALWAYS escaped, so things like "<year:[num]4>" in a snippet can never be
-// mistaken for HTML (a bug the hand-written guide used to have).
+// mistaken for HTML.
 
 const TEXT_ESC = { "&": "&amp;", "<": "&lt;", ">": "&gt;" };
 
@@ -30,8 +30,6 @@ export class ContentError extends Error {
     }
 }
 
-// ---------------------------------------------------------------- front matter
-
 function parseScalar(raw) {
     const v = raw.trim();
     if (v === "true") return true;
@@ -66,8 +64,6 @@ export function parseFrontmatter(source, file) {
     return { data, body: lines.slice(end + 1).join("\n"), bodyLine: end + 2 };
 }
 
-// ------------------------------------------------------------------ variables
-
 /** Replaces {{a.b}} (dot form) outside code, keeping line numbers intact. */
 export function substituteVars(text, vars, file, firstLine = 1) {
     const lines = text.split("\n");
@@ -89,8 +85,6 @@ export function substituteVars(text, vars, file, firstLine = 1) {
             const marker = fm[1] ?? "";
             if (!fence) {
                 fence = marker;
-                // Opt-in: a fence whose info string has the `vars` flag gets variables
-                // substituted inside it (e.g. the clone URL in the install instructions).
                 fenceSubstitutes = /(^|\s)vars(\s|$)/.test(fm[2] ?? "");
             } else if (marker[0] === fence[0] && marker.length >= fence.length && line.trim() === marker) {
                 fence = null;
@@ -144,8 +138,6 @@ function findBacktickClose(s, from, n) {
     return -1;
 }
 
-// -------------------------------------------------------------------- inline
-
 const INLINE_TAGS = new Set(["a", "br", "kbd", "sub", "sup", "span", "abbr", "small", "mark", "em", "strong", "code"]);
 
 function stripInlineMarkup(src) {
@@ -329,8 +321,6 @@ export function renderInline(src) {
     return out;
 }
 
-// --------------------------------------------------------------------- blocks
-
 const FENCE_RE = /^ {0,3}(`{3,}|~{3,})\s*(.*)$/;
 const HEADING_RE = /^(#{1,6})\s+(.*?)\s*$/;
 const ATTR_TAIL_RE = /\s+\{((?:[#.][\w-]+|[\w-]+="[^"]*")(?:\s+(?:[#.][\w-]+|[\w-]+="[^"]*"))*)\}\s*$/;
@@ -715,8 +705,6 @@ class Renderer {
     }
 }
 
-// --------------------------------------------------------------------- public
-
 /**
  * Renders Markdown to HTML.
  * options: {

scripts/render-content.mjs

@@ -2,7 +2,6 @@
 // Prints a fully rendered page (shell + generated content) without starting Vite.
 //   node scripts/render-content.mjs guide          -> stdout
 //   node scripts/render-content.mjs home --out dir -> dir/home.html
-// Handy for diffing generated HTML in a PR and for quick sanity checks.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";

scripts/test/check-engine.test.mjs

@@ -22,7 +22,6 @@ function brokenCopy(mutate) {
     return dir;
 }
 function check(dir) {
-    // no --engine: metadata freshness is covered separately below
     const r = spawnSync(process.execPath, [path.join(root, "scripts/check-engine.mjs"), "--root", dir, "--cuffc", cuffc, "--engine", "/nonexistent"], { encoding: "utf8" });
     return { code: r.status, text: `${r.stdout}\n${r.stderr}` };
 }

src/newsFeed.ts

@@ -1,12 +1,9 @@
 // Renders the "최신 소식" card on the home page by fetching the real
-// CHANGELOG.md straight from GitHub at runtime, so this section can never
-// drift out of sync with the engine the way the rest of the site once did.
+// CHANGELOG.md straight from GitHub at runtime.
 //
 // raw.githubusercontent.com serves with permissive CORS (Access-Control-
 // Allow-Origin: *) and sits behind a CDN, so a plain client-side fetch is
 // fine here — no API token, and none of api.github.com's low rate limits.
-//
-// Which repository / branch / how many entries comes from siteConfig.json.
 import siteConfig from "./siteConfig.json";
 import { parseChangelog, type ChangelogEntry } from "./changelog";
 
@@ -16,7 +13,7 @@ const CHANGELOG_BLOB_URL = `https://github.com/${siteConfig.repo}/blob/${siteCon
 
 const PARSE_OPTIONS = { maxEntries: siteConfig.newsCount, summaryMaxLen: 200 };
 const CACHE_KEY = `cuffscript-site:changelog-feed:v1:${siteConfig.newsCount}`;
-const CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes — avoid refetching on every page view
+const CACHE_TTL_MS = 10 * 60 * 1000; // avoid refetching on every page view
 
 function entriesHtml(entries: ChangelogEntry[]): string {
     return entries

src/styles/base.css

@@ -549,12 +549,8 @@ pre {
 }
 
 /* ---- home page ----
-   A plain, information-dense layout: a light gray backdrop (reusing
-   --bg-elevated) with stacked white "card" sections, plus a slim sticky
-   sidebar — closer to a language reference site (e.g. lua.org) than a
-   marketing landing page. Overriding --radius/--radius-sm/--shadow here
-   makes every reused component (.btn, .ref-table, <pre>, ...) flatter
-   within just this page, without touching the guide or IDE. */
+   --radius/--radius-sm/--shadow are overridden on .home-main so the reused
+   components (.btn, .ref-table, pre) look flatter here only, not in the guide or IDE. */
 
 .home-main {
     flex: 1;