@design-twin/dtwin 0.0.0-stage → 0.1.0

package/src/json-util.ts

@@ -0,0 +1,51 @@
+// Small helpers for the untyped-JSON boundary, shared by bridge/ and design-to-code/ (the layer may
+// import bridge/src; bridge cannot import the layer, so both-sided helpers live here). Dependency-free.
+
+/**
+ * An empty null-prototype record. Use it wherever keys come from untrusted input (component keys, token
+ * names, a map's `kind`): on a plain `{}` those names can resolve to — or write onto — Object.prototype
+ * members ("constructor", "__proto__", "toString"). `Object.create(null)` itself is typed `any`; this is
+ * the one place that asserts its shape.
+ */
+export function nullProto<T>(): Record<string, T> {
+  return Object.create(null) as Record<string, T>;
+}
+
+/** A plain JSON object: not null, not an array. */
+export function isRecord(x: unknown): x is Record<string, unknown> {
+  return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+
+/** Array.isArray for an `unknown`, narrowing to `unknown[]` (the built-in narrows to an untyped array). */
+export function isUnknownArray(x: unknown): x is unknown[] {
+  return Array.isArray(x);
+}
+
+/** A string[] guard for untyped JSON. */
+export function isStringArray(x: unknown): x is string[] {
+  return Array.isArray(x) && x.every((v) => typeof v === "string");
+}
+
+/**
+ * `{ [key]: v }` when `v` is defined, `{}` when it is not — for spreading an optional key into an object
+ * literal (`{ a, ...ifDefined("b", b), c }`) under exactOptionalPropertyTypes, where `b: undefined` no
+ * longer type-checks against `b?: T`. Output is byte-identical to writing `b: b`: JSON.stringify already
+ * drops an undefined-valued key, and the spread sits where the key was, so the key order is unchanged.
+ * Only `undefined` is dropped — `null`, `""`, `0` and `false` are kept, exactly as JSON.stringify keeps them.
+ */
+export function ifDefined<K extends string, V>(key: K, v: V | undefined): Partial<Record<K, V>> {
+  const o: Partial<Record<K, V>> = {};
+  if (v !== undefined) o[key] = v;
+  return o;
+}
+
+/** JSON with object keys sorted at every depth (array order kept; undefined members dropped) — the canonical form a
+ *  hash is taken of (design-to-code plan-binding.ts, probe-steps.ts stepsSha256, plan-record.ts). */
+export function canonical(v: unknown): string {
+  if (Array.isArray(v)) return `[${v.map(canonical).join(",")}]`;
+  if (v && typeof v === "object") {
+    const entries = Object.entries(v).filter(([, x]) => x !== undefined).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, x]) => `${JSON.stringify(k)}:${canonical(x)}`).join(",")}}`;
+  }
+  return JSON.stringify(v ?? null);
+}

package/src/library-layout.ts

@@ -0,0 +1,193 @@
+// The ONE definition of how a LIBRARY-file catalog is split across files — the sibling of
+// design-system-layout.ts, deliberately reusing its filenames and its slim-manifest shape.
+//
+// WHY A SECOND LAYOUT AT ALL. The two catalogs answer different questions and must not overwrite each
+// other:
+//   design/design-system/  = the catalog of the DESIGN file you are building screens from. Its
+//                            variables are the subset your screens actually reference, so it is what
+//                            codegen should emit — generating CSS from the full library would dump
+//                            every unused primitive into the output.
+//   design/libraries/<lib>/ = the COMPLETE catalog of one library file, exported by running the plugin
+//                            inside that library. Its job is lookup/enrichment, not codegen: it is
+//                            where you resolve what a token family really contains, and where a
+//                            component's REAL property definitions live (the design file can only
+//                            infer those from the instances that happen to be present).
+// The join between them is `key` — durable cross-file identity, present on variables, collections,
+// styles and components — NOT names, which collide across libraries.
+//
+// DIRECTORY IDENTITY is `<slug>-<fileKey8>`: a library is a FILE, and fileKey survives a rename, so a
+// renamed library keeps writing to the same directory instead of forking into a second one. The slug is
+// only there to keep the path human-readable. When figma.fileKey is unavailable the plugin says so in
+// hygiene and we fall back to the slug alone — a rename then forks the directory, which is why it is
+// warned about rather than silently absorbed.
+//
+// Kept dependency-free (no Node imports, ES2019-safe) for the same reason as its siblings: the bridge
+// CLI imports it and esbuild inlines it into the plugin bundle, so the disk writer and the
+// browser-download writer emit the identical set of files.
+
+import type { PageLayoutFile } from "./pages-layout.ts";
+import { ifDefined } from "./json-util.ts";
+import { DESIGN_SYSTEM_FILES, STYLE_KINDS, byStyleKey, stylesOf } from "./design-system-layout.ts";
+import type {
+  TokensDoc, StylesDoc, HygieneDoc, CatalogComponent, ComponentsCatalog, DesignSystemDoc, LibraryStamp, LibraryCounts, LibraryManifest,
+  LibrariesIndexRow, LibrariesIndex,
+} from "./doc-types.ts";
+
+/** Every document the library split writes, in `files` order (the manifest last). */
+export type LibraryFileData =
+  | (TokensDoc & LibraryStamp) | (StylesDoc & LibraryStamp) | (ComponentsCatalog & LibraryStamp) | (HygieneDoc & LibraryStamp) | LibraryManifest;
+
+export interface LibraryLayout {
+  /** Every file to write, INCLUDING the directory's own index.json (last). */
+  files: Array<PageLayoutFile<LibraryFileData>>;
+  /** The slim manifest alone: stamp + `source` + `files` pointer map + `counts` + `publish`. */
+  manifest: LibraryManifest;
+  counts: LibraryCounts;
+  /** The full relative directory the parts live under ("libraries/<slug>-<fileKey8>"). */
+  dir: string;
+  /** Just the leaf directory name — the identity a libraries/index.json row is keyed on. */
+  dirName: string;
+}
+
+export const ROOT = "libraries";
+export const INDEX = "index.json"; // per-directory self-description; also the name of the libraries/ index
+// The token, style and hygiene parts keep design-system/'s file names (the style files one per STYLE_KINDS row); the
+// catalog differs: a library's own full definitions are components.json (design-system/ splits local and
+// library-sampled components).
+const { TOKENS, HYGIENE } = DESIGN_SYSTEM_FILES;
+export const COMPONENTS = "components.json";
+/** Every file buildLibraryLayout writes in a libraries/<dir>/, in `files` order (the manifest, INDEX, last). */
+export const LIBRARY_FILE_NAMES: readonly string[] = [TOKENS, ...STYLE_KINDS.map((row) => row.file), COMPONENTS, HYGIENE, INDEX];
+
+// Filesystem-safe, stable, lowercase. Same spirit as pages-layout.ts's `safe`.
+function slug(s: unknown): string {
+  return String(s || "library")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40) || "library";
+}
+
+/**
+ * @param ds   the plugin's designSystem doc, as produced by collectLibraryFile
+ * @param sep  path separator: "/" for real directories, "__" for flat download names.
+ * @returns    `files` is every file to write INCLUDING the directory's own index.json (last).
+ */
+export function buildLibraryLayout(ds: DesignSystemDoc | null | undefined, sep: string): LibraryLayout {
+  const d: DesignSystemDoc = ds || {};
+  const s = sep || "/";
+  const source = d.source;
+  const fileKey = source && source.fileKey ? String(source.fileKey) : "";
+  // Only the first 8 chars: enough to disambiguate two libraries, short enough to keep the path
+  // readable. The FULL key is recorded in the index, so nothing depends on the truncation.
+  const dirName = slug((source && source.libraryName) || d.file) + (fileKey ? "-" + fileKey.slice(0, 8) : "");
+  const dir = ROOT + s + dirName;
+  const join = (name: string): string => dir + s + name;
+
+  // The stamp every split file carries, plus `source`. `exportedAt`/`file` stay top-level and
+  // unmodified so export-verdict.ts and design-to-code/drift-lint.ts keep reading them off whichever file they
+  // are handed; `source` is additive and tells a consumer this is a library catalog, not a design
+  // file's — a distinction that is otherwise invisible, because inside the library file every object
+  // is local and `remote` is therefore false on all of them.
+  const stamp: LibraryStamp = {
+    ...ifDefined("exportedAt", d.exportedAt), ...ifDefined("file", d.file), ...ifDefined("colorProfile", d.colorProfile), ...ifDefined("source", d.source),
+  };
+
+  const variables = Array.isArray(d.variables) ? d.variables : [];
+  const collections = Array.isArray(d.collections) ? d.collections : [];
+  const hygiene = Array.isArray(d.hygiene) ? d.hygiene : [];
+
+  // Inside a library file every component IS local, so there is no local/library partition to make
+  // (design-system-layout.ts splits on `remote` because a design file's catalog genuinely mixes both).
+  // A remote entry here would belong to a DIFFERENT library — that library's export to make, not this
+  // one's — so it is dropped and reported rather than filed under this library's name.
+  const all: CatalogComponent[] = Array.isArray(d.components) ? d.components : [];
+  const components = all.filter((c) => !(c && c.remote === true));
+  const foreign = all.length - components.length;
+  const hyg = foreign
+    ? hygiene.concat(
+        foreign + " component(s) consumed from ANOTHER library were dropped from this catalog — " +
+          "export that library separately; a library's catalog only claims what it defines."
+      )
+    : hygiene;
+
+  const files: Array<PageLayoutFile<LibraryFileData>> = [
+    { path: join(TOKENS), data: Object.assign({}, stamp, { collections, variables }) },
+    ...STYLE_KINDS.map((row) => ({ path: join(row.file), data: Object.assign({}, stamp, { styles: stylesOf(d.styles, row.kind) }) })),
+    { path: join(COMPONENTS), data: Object.assign({}, stamp, { components }) },
+    { path: join(HYGIENE), data: Object.assign({}, stamp, { hygiene: hyg }) },
+  ];
+
+  // Publish status is only meaningful in library mode, so summarise it where a human will see it: how
+  // much of this library is actually live for consumers vs. sitting unpublished in the file.
+  const publishCounts: Record<string, number> = {};
+  for (const c of components) if (c && c.publish) publishCounts[c.publish] = (publishCounts[c.publish] || 0) + 1;
+  for (const v of variables) if (v && v.publish) publishCounts[v.publish] = (publishCounts[v.publish] || 0) + 1;
+
+  const counts: LibraryCounts = {
+    collections: collections.length,
+    variables: variables.length,
+    ...byStyleKey((row) => stylesOf(d.styles, row.kind).length),
+    components: components.length,
+    hygiene: hyg.length,
+  };
+
+  const manifest: LibraryManifest = Object.assign({}, stamp, {
+    // Same pointer-map shape as design-system.json: relative paths exactly as written, separator and
+    // all, so a consumer joins them against the export dir and needs to know nothing else.
+    files: {
+      tokens: join(TOKENS),
+      ...byStyleKey((row) => join(row.file)),
+      components: join(COMPONENTS),
+      hygiene: join(HYGIENE),
+    },
+    counts,
+    ...(Object.keys(publishCounts).length ? { publish: publishCounts } : {}),
+  });
+  files.push({ path: join(INDEX), data: manifest });
+
+  return { files, manifest, counts, dir, dirName };
+}
+
+/**
+ * The libraries/ index: one row per library exported so far. Merged rather than overwritten, because
+ * each library is a SEPARATE plugin run in a SEPARATE file — a second library's export must not erase
+ * the first one's row. Rows are keyed by directory name (fileKey-derived), so re-exporting the same
+ * library replaces its own row and nothing else.
+ *
+ * @param prev   the previously written index (untyped JSON read back from disk), or null/undefined
+ *               on the first export
+ * @param built  the return value of buildLibraryLayout
+ * @returns      the index to write
+ */
+export function mergeLibrariesIndex(prev: unknown, built: LibraryLayout): LibrariesIndex {
+  const prevLibraries = prev && typeof prev === "object" && "libraries" in prev ? prev.libraries : undefined;
+  const rows: unknown[] = Array.isArray(prevLibraries) ? prevLibraries.slice() : [];
+  const m = built.manifest;
+  const source = m.source;
+  const row: LibrariesIndexRow = {
+    dir: built.dirName,
+    ...ifDefined("libraryName", (source && source.libraryName) || m.file),
+    ...ifDefined("file", m.file),
+    ...ifDefined("fileKey", source && source.fileKey),
+    ...ifDefined("collectionKeys", source && source.collectionKeys),
+    ...ifDefined("exportedAt", m.exportedAt),
+    counts: m.counts,
+    ...ifDefined("publish", m.publish),
+    index: built.dirName + "/" + INDEX,
+  };
+  const i = rows.findIndex((r) => dirOf(r) === built.dirName);
+  if (i >= 0) rows[i] = row;
+  else rows.push(row);
+  rows.sort((a, b) => String(dirOf(a)).localeCompare(String(dirOf(b))));
+  // No top-level `file`/`exportedAt` stamp here on purpose: this index spans SEVERAL Figma files, and
+  // `file` is contractually "which one file did this come from" (export-verdict.ts reads it as
+  // sourceFile). Each row carries its own stamp instead, so per-library staleness stays visible.
+  return { libraries: rows, generatedAt: new Date().toISOString() };
+}
+
+// A previous row's `dir`, read the way plain JS reads `r.dir` (undefined for null/undefined, and for
+// anything without a `dir`) — rows on disk are untyped JSON.
+function dirOf(r: unknown): unknown {
+  return r !== null && typeof r === "object" && "dir" in r ? r.dir : undefined;
+}

package/src/node-id.ts

@@ -0,0 +1,69 @@
+// Figma node-id parsing — the ONE place that knows what a node id looks like and how it hides in a
+// Figma URL. Both Node-side consumers (the MCP write/read server and the seed-components CLI) import
+// this instead of carrying their own regex pair, which had already drifted into disagreeing about
+// which ids are valid.
+//
+// A link may carry the id in any of four forms:
+//   dash "1-2" · colon "1:2" · percent-encoded "1%3A2" · nested-instance path "I1-2;3-4"
+// The Plugin API wants the COLON form, so that's the canonical form everything here returns.
+
+// The node-id token inside a URL, captured loosely and validated by normalizeNodeId. Matching loosely
+// matters: a regex that only accepted `[0-9]+-[0-9]+` silently skipped the other three forms.
+export const ID = "[A-Za-z0-9%:;_-]+";
+const NODE_ID_RE = new RegExp("node-id=(" + ID + ")");
+
+// URL is a global in Node, but NOT in the Figma plugin's ES2019 lib (no DOM types there), and this
+// module type-checks under both tsconfigs. A module-scoped ambient declaration of exactly the surface
+// used below — emits nothing, so at runtime it is the real global (in a realm without one, the
+// `new URL` throws and parseNodeId's catch falls through to the loose match, as it always did).
+declare const URL: new (input: string) => { searchParams: { get(name: string): string | null } };
+
+function decode(s: string): string {
+  try { return decodeURIComponent(s); } catch (e) { return s; } // malformed escape — use it verbatim
+}
+
+// The colon form: "1:2", or a nested-instance path "I1:2;3:4".
+const COLON_ID_RE = /^I?\d+:\d+(?:[;:]\d+:\d+)*$/;
+
+/** True when `s` already IS a node id in the Plugin API's colon form ("1:2", "I1:2;3:4") — what a query
+ *  typed as an id looks like, as opposed to a name. A bare number is not one here (it reads as a name). */
+export function isNodeId(s: string): boolean {
+  return COLON_ID_RE.test(s);
+}
+
+// A raw node-id token -> the Plugin API's colon form ("1:2"), or undefined when it isn't an id.
+function normalizeNodeId(raw: unknown): string | undefined {
+  if (!raw) return undefined;
+  const s = decode(String(raw).trim()).replace(/-/g, ":");
+  // "1:2", "I1:2;3:4" (nested instance path), or a bare numeric id.
+  return COLON_ID_RE.test(s) || /^\d+$/.test(s) ? s : undefined;
+}
+
+// A full Figma URL, a `…node-id=…` fragment, or a bare id -> colon form, or undefined when there's
+// no id to be found (callers surface their own friendly hint).
+export function parseNodeId(input: unknown): string | undefined {
+  if (!input) return undefined;
+  const s = String(input).trim();
+  try {
+    // searchParams already percent-decodes, so this branch hands normalizeNodeId a decoded token.
+    const nid = new URL(s).searchParams.get("node-id");
+    if (nid) return normalizeNodeId(nid);
+  } catch (e) { /* not a full URL — fall through to the loose match */ }
+  const m = s.match(NODE_ID_RE);
+  if (m) return normalizeNodeId(m[1]);
+  return normalizeNodeId(s); // bare id
+}
+
+// The LENIENT twin of parseNodeId, and the form every consumer actually wants: normalize when the
+// token is recognisable, otherwise pass the raw token through untouched so the plugin — not this
+// parser — gets to be the authority on what resolves. Every front-end (plugin collector, CLI, MCP)
+// was spelling `parseNodeId(x) || x` itself, in three slightly different ways; that put half of this
+// module's contract back into three files, which is the exact drift it exists to prevent.
+export function toNodeId(raw: unknown): string {
+  return parseNodeId(raw) || (raw == null ? "" : String(raw));
+}
+
+// NODE_ID_RE/normalizeNodeId stay module-private: exporting them invited a consumer to re-derive
+// half the contract, which is the drift this file exists to prevent. isNodeId hands out the colon-form
+// grammar as a predicate, so a consumer asking "is this already an id?" needs no regex of its own. ID is
+// exported only because seed-components.ts composes it into its own source-scanning regexes.