flet-box 1.1.1 → 1.1.3

package/bin/cli.js

@@ -15,6 +15,10 @@ import path from "path";
 import { createProject } from "./commands/create.js";
 import { checkApi } from "./commands/checkApi.js";
 import { checkUi } from "./commands/checkUi.js";
+import { verify, watchVerify, formatReport } from "./commands/verify.js";
+import { metrics } from "./commands/metrics.js";
+import { report } from "./commands/report.js";
+import { tools } from "./commands/tools.js";
 import { auditFix } from "./commands/auditFix.js";
 import { toPng } from "./commands/toPng.js";
 import { images } from "./commands/images.js";
@@ -91,8 +95,22 @@ ${cmd("check-ui", "Clean-UI gate: tokens, 8-based scale, tap targets, WCAG contr
 ${cmd("   └─ --tokens", "print the measured contrast of every color token")}
 ${cmd("   └─ --strict", "fail on contrast warnings too")}
 ${cmd("   └─ alias", "ui | checkUi")}
+${cmd("verify", "Every gate at once: one report, one exit code")}
+${cmd("   └─ --only <gate>", "syntax | api | types | ui | structure | surface | tests")}
+${cmd("   └─ --no-tests", "the static gates only; the project's suites run alone")}
+${cmd("   └─ --fix", "the mechanical repair first, then the gates")}
+${cmd("   └─ --json", "the report as data")}
+${cmd("   └─ alias", "check-all")}
+${cmd("report", "Read-only diagnosis: a verdict per file and what to do next")}
+${cmd("   └─ --json | --md", "the same facts as data or Markdown")}
+${cmd("   └─ --html [--out <file>]", "one self-contained page (.fletbox/reports/report.html)")}
+${cmd("   └─ --tests", "also run the project's own suites")}
+${cmd("tools [--emit]", "The read-only toolkit: one question, one command")}
+${cmd("mcp", "Serve that toolkit over MCP stdio (read-only)")}
+${cmd("metrics", "The north metric: code that passed with no correction")}
+${cmd("   └─ --log <file>", "read another project's log")}
 ${cmd("audit-fix", "Rewrite broken imports, missing imports and misspelled props")}
-${cmd("   └─ --only imports|props", "run one repair instead of both")}
+${cmd("   └─ --only imports|props|migrations", "run one repair instead of the others")}
 ${cmd("   └─ alias", "fix-imports | fix-path-imports | auditFix")}
 ${cmd("to-png [dir]", "Convert JPEG/BMP/GIF images to PNG, no dependencies")}
 ${cmd("   └─ --replace", "remove each source after its PNG was written and read back")}
@@ -124,6 +142,7 @@ ${cmd("--version | --help", "Version and this help")}
 ${section("⚙️", "OPTIONS")}
 ${opt("--port <n>, -p <n>", "Port (default 8000) — asked if not provided")}
 ${opt("--hot", "Hot reload with run")}
+${opt("--verify", "Run the gates on every edit while the server runs")}
 ${opt("--quiet", "No request logging")}
 ${opt("--dry-run | --list", "kill-server: just list, do not kill")}
 
@@ -167,6 +186,7 @@ const parseFlags = () => {
     logRequests: true,
     hot: false,
     dryRun: false,
+    verify: false,
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -187,6 +207,8 @@ const parseFlags = () => {
       flags.logRequests = false;
     } else if (arg === "--hot" || arg === "--hot-reload") {
       flags.hot = true;
+    } else if (arg === "--verify") {
+      flags.verify = true;
     } else if (arg === "--dry-run" || arg === "--list" || arg === "--check") {
       flags.dryRun = true;
     }
@@ -242,6 +264,24 @@ async function main() {
     switch (command) {
       case "create":
       case "new":
+        // `flet-box create --help` must print the help, not scaffold a folder
+        // named `--help`: that stray clone lands inside the project and the
+        // structure gate starts reporting SOURCE_OUTSIDE_ROOT for every module
+        // in it.
+        if (projectName && projectName.startsWith("-")) {
+          if (projectName === "--help" || projectName === "-h") {
+            showHelp();
+            break;
+          }
+          console.error(c("red", `❌ Unknown option: ${projectName}`));
+          console.log(
+            c(
+              "gray",
+              "Usage: flet-box create <project-name> [--adaptive|--blank|--full|--sidebar|--template <name>|--repo user/repo]",
+            ),
+          );
+          process.exit(1);
+        }
         if (!projectName) {
           console.error(c("red", "❌ Error: Project name required"));
           console.log(
@@ -328,6 +368,40 @@ async function main() {
         break;
       }
 
+      case "verify":
+      case "check-all": {
+        const { exitCode } = await verify(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
+      case "metrics": {
+        const { exitCode } = await metrics(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
+      case "report": {
+        const { exitCode } = await report(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
+      case "tools":
+      case "toolkit": {
+        const { exitCode } = await tools(args.slice(1));
+        if (exitCode) process.exit(exitCode);
+        break;
+      }
+
+      case "mcp": {
+        // Lazy: the stdio server takes over the process, and nothing else in
+        // the CLI should pay for loading it.
+        const { serveStdio } = await import("./mcp.js");
+        serveStdio();
+        break;
+      }
+
       case "audit-fix":
       case "auditFix":
       case "fix-imports":
@@ -410,6 +484,19 @@ async function main() {
         // which are devDependencies: a consumer installing `flet-box` from npm
         // has neither, so loading them at module scope would break every CLI
         // command for them. Import them when a server is actually started.
+        if (flags.verify) {
+          console.log(
+            c("dim", "🔎 verify is watching src/ — every edit is checked against the gates"),
+          );
+          watchVerify({
+            root: process.cwd(),
+            onReport: (report) => {
+              console.log("");
+              for (const line of formatReport(report)) console.log(line);
+              console.log("");
+            },
+          });
+        }
         await (await import("./commands/runServer.js")).runDevServer({
           spaMode: false,
           hotReload: flags.hot,

package/bin/commands/auditFix.js

@@ -1,15 +1,17 @@
 /**
  * `flet-box audit-fix` — write what `check-api` only reports.
  *
- * Two repairs, both anchored to spans the gate already knows how to find:
+ * Three repairs, all anchored to spans the gate already knows how to find:
  *
- *   imports  a relative path that does not resolve, a name the target module
- *            never exports, a default import from a module without a default,
- *            and identifiers used with no import at all (a flet-box export, or
- *            a Node builtin used as `path.join(…)`).
- *   props    a key inside `Widget({ … })` that neither the widget's declared
- *            props, the structural props, nor the engine registry knows —
- *            `chilldren` → `children`, `postion` → `position`.
+ *   imports    a relative path that does not resolve, a name the target module
+ *              never exports, a default import from a module without a default,
+ *              and identifiers used with no import at all (a flet-box export, or
+ *              a Node builtin used as `path.join(…)`).
+ *   props      a key inside `Widget({ … })` that neither the widget's declared
+ *              props, the structural props, nor the engine registry knows —
+ *              `chilldren` → `children`, `postion` → `position`.
+ *   migrations a key inside `Widget({ … })` that the widget still honours but no
+ *              longer recommends — `Radio({ onSelect })` → `Radio({ onPress })`.
  *
  * A rewrite only happens when the intended name is unambiguous: one candidate,
  * edit distance small enough that no real name could collide with it. Anything
@@ -23,6 +25,7 @@ import { c, banner, section } from "../utils/colors.js";
 import { neutralise } from "../utils/neutralise.js";
 import { resolveLocalModule, readModuleExports } from "../utils/moduleExports.js";
 import { resolveInterfaceProps } from "../utils/dtsProps.js";
+import { deprecationFor } from "../../src/widget-factory/deprecations.js";
 import {
   STRUCTURAL_PROPS,
   collectSources,
@@ -252,9 +255,13 @@ const strictMatch = (wanted, candidates) => {
 /**
  * Top-level keys of an object literal, with their spans.
  *
+ * `entryEnd` is where the whole entry ends — the key *and* its value — which
+ * is what a removal has to take, since deleting a key without its value would
+ * leave the value behind.
+ *
  * @param {string} code comment/string-free source
  * @param {number} open index of `{`
- * @returns {{ keys: Array<{ name: string, start: number, end: number }>, opaque: boolean }}
+ * @returns {{ keys: Array<{ name: string, start: number, end: number, entryEnd: number }>, opaque: boolean }}
  */
 const literalKeySpans = (code, open) => {
   const keys = [];
@@ -268,6 +275,7 @@ const literalKeySpans = (code, open) => {
     const at = entryStart + (text ? lead : 0);
     current = "";
     if (!text) return;
+    const entryEnd = at + text.length;
     if (text.startsWith("...")) {
       opaque = true;
       return;
@@ -275,9 +283,9 @@ const literalKeySpans = (code, open) => {
     const key = /^(?:async\s+)?['"]?([A-Za-z_$][\w$]*)['"]?\s*:/.exec(text);
     if (key) {
       const start = at + text.indexOf(key[1]);
-      keys.push({ name: key[1], start, end: start + key[1].length });
+      keys.push({ name: key[1], start, end: start + key[1].length, entryEnd });
     } else if (/^[A-Za-z_$][\w$]*$/.test(text)) {
-      keys.push({ name: text, start: at, end: at + text.length });
+      keys.push({ name: text, start: at, end: at + text.length, entryEnd });
     }
   };
   for (let i = open; i < code.length; i++) {
@@ -518,20 +526,15 @@ const planImports = (file, code, api, allSources) => {
 };
 
 /**
- * Plan the prop-key rewrites for one file.
+ * The widgets an app imported from flet-box, as `local name → exported name`.
  *
- * @param {string} file
- * @param {string} code
- * @param {object} api
- * @returns {{ edits: Edit[], skipped: string[] }}
+ * Only capitalised exports are widgets; the rest of the barrel is functions
+ * and tools, and a call to one of those never carries a props object.
+ *
+ * @param {string} withStrings Neutralised source, strings kept.
+ * @returns {Map<string, string>}
  */
-const planProps = (file, code, api) => {
-  const edits = [];
-  const skipped = [];
-  const rel = path.relative(api.root, file);
-  const withStrings = neutralise(code, { keepStrings: true });
-  const body = neutralise(code);
-
+const fletWidgetImports = (withStrings) => {
   const localToWidget = new Map();
   for (const match of withStrings.matchAll(IMPORT_RE)) {
     if (match[2] !== "flet-box") continue;
@@ -546,6 +549,54 @@ const planProps = (file, code, api) => {
       if (/^[A-Z]/.test(exported)) localToWidget.set(local, exported);
     }
   }
+  return localToWidget;
+};
+
+/**
+ * The value written after a key of an object literal, or null.
+ *
+ * @param {string} code Source with the strings kept — a neutralised string
+ *   keeps its quotes but loses its content, and the content is the value.
+ * @param {{ end: number }} key The key's span.
+ * @returns {string|null}
+ */
+const keyValue = (code, key) => {
+  const match = /^\s*:\s*['"]?([^'"\s,}]+)/.exec(code.slice(key.end, key.end + 80));
+  return match ? match[1] : null;
+};
+
+/**
+ * The span that removes one entry of an object literal, comma included.
+ *
+ * @param {Array<{ start: number, end: number, entryEnd: number }>} keys
+ * @param {number} index The entry to remove.
+ * @returns {{ start: number, end: number }}
+ */
+const removalSpan = (keys, index) => {
+  const key = keys[index];
+  const next = keys[index + 1];
+  if (next) return { start: key.start, end: next.start };
+  const prev = keys[index - 1];
+  if (prev) return { start: prev.entryEnd, end: key.entryEnd };
+  return { start: key.start, end: key.entryEnd };
+};
+
+/**
+ * Plan the prop-key rewrites for one file.
+ *
+ * @param {string} file
+ * @param {string} code
+ * @param {object} api
+ * @returns {{ edits: Edit[], skipped: string[] }}
+ */
+const planProps = (file, code, api) => {
+  const edits = [];
+  const skipped = [];
+  const rel = path.relative(api.root, file);
+  const withStrings = neutralise(code, { keepStrings: true });
+  const body = neutralise(code);
+
+  const localToWidget = fletWidgetImports(withStrings);
 
   for (const [local, exported] of localToWidget) {
     const iface = `${exported}Props`;
@@ -579,6 +630,103 @@ const planProps = (file, code, api) => {
   return { edits, skipped };
 };
 
+/**
+ * Plan the renames an app can make without touching a line by hand.
+ *
+ * A prop the framework still honours but no longer recommends is not broken
+ * code, so `check-api` has nothing to say about it — but every screen that
+ * keeps the old name keeps an old spelling forever. The table in
+ * `src/widget-factory/deprecations.js` is the list, and it is per widget
+ * because the same name means different things in different widgets.
+ *
+ * The rewrite only happens when it is provably the same call: the widget has to
+ * declare the old name, it has to declare the new one, and the call must not
+ * already carry the new one (two callbacks for one event is a decision, not a
+ * rename).
+ *
+ * A row with no target (`to: null`) is a prop nobody reads any more: the key
+ * is removed, together with the comma that held it.
+ *
+ * @param {string} file
+ * @param {string} code
+ * @param {object} api
+ * @returns {{ edits: Edit[], skipped: string[] }}
+ */
+const planMigrations = (file, code, api) => {
+  const edits = [];
+  const skipped = [];
+  const rel = path.relative(api.root, file);
+  const withStrings = neutralise(code, { keepStrings: true });
+  const body = neutralise(code);
+
+  for (const [local, exported] of fletWidgetImports(withStrings)) {
+    const iface = `${exported}Props`;
+    if (!api.interfaces.has(iface)) continue;
+    const declared = resolveInterfaceProps(api.interfaces, iface);
+    const callRe = new RegExp(`\\b${escapeRe(local)}\\s*\\(\\s*\\{`, "g");
+    let call;
+    while ((call = callRe.exec(body))) {
+      const open = call.index + call[0].length - 1;
+      const { keys, opaque } = literalKeySpans(body, open);
+      if (opaque) continue;
+      const byName = new Map(keys.map((entry) => [entry.name, entry]));
+
+      for (const key of keys) {
+        const rule = deprecationFor(exported, key.name);
+        if (!rule || !rule.to) continue;
+        if (!declared.has(rule.from) || !declared.has(rule.to)) {
+          skipped.push(`${rel}: ${exported}({ ${key.name} }) — the widget does not declare the pair`);
+          continue;
+        }
+        const inert = (rule.guard || []).find((name) => byName.has(name));
+        if (inert) {
+          skipped.push(
+            `${rel}: ${exported}({ ${key.name} }) — ${inert} is already there, so the old name does nothing`,
+          );
+          continue;
+        }
+        let target = rule.to;
+        if (rule.alternate) {
+          const side = byName.get(rule.alternate.prop);
+          if (side && keyValue(withStrings, side) === rule.alternate.value) {
+            target = rule.alternate.to;
+          }
+        }
+        if (byName.has(target)) {
+          skipped.push(
+            `${rel}: ${exported}({ ${key.name} }) — ${target} is already there; two callbacks for one event is your call`,
+          );
+          continue;
+        }
+        edits.push({
+          start: key.start,
+          end: key.end,
+          text: target,
+          note: `${exported}({ ${c("brightRed", key.name)} }) → ${c("brightGreen", target)}`,
+          kind: "migration",
+        });
+      }
+
+      // The removals run after the renames: a prop that only meant something
+      // next to another one goes away with it.
+      for (let index = 0; index < keys.length; index++) {
+        const key = keys[index];
+        const rule = deprecationFor(exported, key.name);
+        if (!rule || rule.to) continue;
+        if (!declared.has(rule.from)) continue;
+        edits.push({
+          ...removalSpan(keys, index),
+          text: "",
+          note: `${exported}({ ${c("brightRed", key.name)} }) → ${c("brightGreen", "removed")}`,
+          kind: "migration",
+        });
+      }
+    }
+  }
+
+  return { edits, skipped };
+};
+
 /**
  * Apply planned edits to one file.
  *
@@ -615,13 +763,14 @@ export const auditFix = async (argv = [], io = {}) => {
     return i >= 0 && argv[i + 1] ? path.resolve(argv[i + 1]) : process.cwd();
   })();
   const onlyFlag = argv.includes("--only") ? argv[argv.indexOf("--only") + 1] : null;
-  if (onlyFlag && !["imports", "props"].includes(onlyFlag)) {
-    print(c("red", `--only expects "imports" or "props", got "${onlyFlag}"`));
+  if (onlyFlag && !["imports", "props", "migrations"].includes(onlyFlag)) {
+    print(c("red", `--only expects "imports", "props" or "migrations", got "${onlyFlag}"`));
     return { exitCode: 1, changed: [], untouched: [] };
   }
   const only = {
     imports: !onlyFlag || onlyFlag === "imports",
     props: !onlyFlag || onlyFlag === "props",
+    migrations: !onlyFlag || onlyFlag === "migrations",
   };
 
   let api;
@@ -637,7 +786,11 @@ export const auditFix = async (argv = [], io = {}) => {
   const files = collectSources(root);
   const changed = [];
   const untouched = [];
-  const passes = [only.imports && "imports", only.props && "props"].filter(Boolean);
+  const passes = [
+    only.imports && "imports",
+    only.props && "props",
+    only.migrations && "migrations",
+  ].filter(Boolean);
 
   print(banner("🔧 FletBox audit fix", `${files.length} file(s) · ${passes.join(" + ")}`));
 
@@ -651,6 +804,7 @@ export const auditFix = async (argv = [], io = {}) => {
     const runs = [];
     if (only.imports) runs.push(() => planImports(file, text, api, files));
     if (only.props) runs.push(() => planProps(file, text, api));
+    if (only.migrations) runs.push(() => planMigrations(file, text, api));
     for (const run of runs) {
       const plan = run();
       untouched.push(...plan.skipped);
@@ -673,7 +827,7 @@ export const auditFix = async (argv = [], io = {}) => {
 
   print(
     changed.length
-      ? `\n${c("brightGreen", `${changed.length} file(s) rewritten`)} ${c("gray", "— run npm run check to confirm, and git diff to review.")}`
+      ? `\n${c("brightGreen", `${changed.length} file(s) rewritten`)} ${c("gray", "— run npm run verify to confirm, and git diff to review.")}`
       : c("gray", "\nNothing to rewrite — every import resolves and every prop is known."),
   );
   return { exitCode: 0, changed, untouched };

package/bin/commands/checkApi.js

@@ -37,6 +37,7 @@ import {
 import { c, banner, section } from "../utils/colors.js";
 import { neutralise } from "../utils/neutralise.js";
 import { resolveLocalModule, readModuleExports } from "../utils/moduleExports.js";
+import { deprecationFor } from "../../src/widget-factory/deprecations.js";
 
 const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -538,7 +539,7 @@ const ERROR_CODES = new Set([
   "MISSING_EXPORT",
 ]);
 
-const SEVERITY = {
+export const SEVERITY = {
   WRONG_STACK: "error",
   UNKNOWN_EXPORT: "error",
   UNKNOWN_PROP: "error",
@@ -600,7 +601,7 @@ const entry = (prop, info, api) => {
  * @param {string} projectRoot
  * @returns {string} written path
  */
-const emitCheatsheet = (api, projectRoot) => {
+export const emitCheatsheet = (api, projectRoot) => {
   const widgetNames = api.exports
     .filter((name) => /^[A-Z]/.test(name) && api.interfaces.has(`${name}Props`))
     .sort();
@@ -614,6 +615,10 @@ const emitCheatsheet = (api, projectRoot) => {
       `Regenerate with \`flet-box check-api --emit-api\`.`,
   );
   out.push(`Widgets: ${widgetNames.length} · engine props: ${api.ALL_PROPS.length}`);
+  out.push(
+    `A prop marked \`(deprecated → x)\` still works and is not the name to write; ` +
+      `\`npm run fix\` renames the call it can prove.`,
+  );
   out.push(``);
   out.push(`## Common props (every widget)`);
   out.push(
@@ -629,7 +634,13 @@ const emitCheatsheet = (api, projectRoot) => {
       [...own]
         .map(([prop, info]) => {
           const type = info.type.length > 46 ? `${info.type.slice(0, 43)}…` : info.type;
-          return `${prop}${info.optional ? "?" : ""}: ${type}`;
+          // The cheatsheet is the first file an agent reads, so a renamed prop has
+          // to say so here. Without the marker `onPress` and `onToggle` look like
+          // two equally good names, and half the calls built from this file carry
+          // the one the framework is trying to retire.
+          const rule = deprecationFor(name, prop);
+          const mark = rule ? ` (deprecated → ${rule.to ?? "removed"})` : "";
+          return `${prop}${info.optional ? "?" : ""}: ${type}${mark}`;
         })
         .join(" · "),
     );