@reqvire-org/ads 0.0.0-stage → 0.2.9

package/dist/tokens.mjs

@@ -0,0 +1,142 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import postcss from "postcss";
+import valueParser from "postcss-value-parser";
+import { loadConfig, sourceFiles } from "./config.mjs";
+import { foundationFiles, isSharedToken, tokenContract } from "./token-policy.mjs";
+import { checkComponentVariable } from "./boundaries.mjs";
+
+export { tokenContract };
+
+export function references(value) {
+  const refs = [];
+  valueParser(value).walk((node) => {
+    if (node.type !== "function" || node.value !== "var") return;
+    const name = node.nodes.find((child) => child.type === "word")?.value;
+    if (name?.startsWith("--")) refs.push({ name, fallback: node.nodes.some((child) => child.type === "div" && child.value === ",") });
+  });
+  return refs;
+}
+
+function context(decl) {
+  const parts = [];
+  for (let parent = decl.parent; parent; parent = parent.parent) {
+    if (parent.type === "rule") parts.unshift(parent.selector);
+    // Layers affect precedence, not the theme condition.
+    if (parent.type === "atrule" && parent.name !== "layer") parts.unshift(`@${parent.name} ${parent.params}`);
+  }
+  return parts.join(" > ");
+}
+
+function matchesType(value, type) {
+  if (/^(?:calc|min|max|clamp|env)\(/.test(value)) return true; // Browser expressions need runtime validation.
+  if (/^(?:inherit|initial|unset|revert(?:-layer)?)$/.test(value)) return true;
+  switch (type) {
+    case "color": return /^(?:#[\da-f]{3,8}|[a-z][\w-]*|(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color|color-mix|light-dark)\([\s\S]+\))$/i.test(value);
+    case "dimension": return /^[-+]?(?:\d*\.)?\d+(?:px|r?em|ch|ex|cap|lh|rlh|v[wh]|[sld]v[wh]|vmin|vmax|cm|mm|in|pt|pc|%)$/i.test(value) || /^[-+]?0(?:\.0+)?$/.test(value);
+    case "duration": return /^[-+]?(?:\d*\.)?\d+m?s$/i.test(value);
+    case "number": return /^[-+]?(?:\d*\.)?\d+$/.test(value);
+    case "easing": return /^(?:linear|ease(?:-in|-out|-in-out)?|step-start|step-end|(?:cubic-bezier|steps|linear)\([\s\S]+\))$/.test(value);
+    case "shadow": return value === "none" || /(?:\d(?:px|rem|em)|var\()/.test(value);
+    case "fontFamily": return Boolean(value.trim()) && !/^[-+]?\d/.test(value);
+    default: return true;
+  }
+}
+
+export function inspectTokens(directory) {
+  const options = loadConfig(directory);
+  const { root, dsRoot, config } = options;
+  const definitions = new Map();
+  const diagnostics = [];
+  const files = sourceFiles(path.join(dsRoot, config.tokenDir)).filter((file) => file.endsWith(".css"));
+  files.sort((a, b) => foundationFiles.indexOf(path.basename(a)) - foundationFiles.indexOf(path.basename(b)) || a.localeCompare(b));
+  for (const file of files) {
+    let css;
+    try { css = postcss.parse(readFileSync(file, "utf8"), { from: file }); }
+    catch (error) {
+      diagnostics.push({ rule: "css-syntax", file: path.relative(root, file), line: error.line ?? 1, column: error.column ?? 1, message: error.reason ?? error.message });
+      continue;
+    }
+    css.walkDecls((decl) => {
+      if (!decl.prop.startsWith("--")) return;
+      const ownership = checkComponentVariable(decl.prop, file, options);
+      if (ownership) diagnostics.push({ rule: ownership.rule, file: path.relative(root, file), line: decl.source.start.line, column: decl.source.start.column, message: ownership.message });
+      const definition = {
+        file: path.relative(root, file).replaceAll("\\", "/"),
+        line: decl.source.start.line,
+        column: decl.source.start.column,
+        scope: context(decl),
+        value: decl.value,
+      };
+      if (!definitions.has(decl.prop)) definitions.set(decl.prop, []);
+      definitions.get(decl.prop).push(definition);
+    });
+  }
+  const base = new Map();
+  const scopes = new Map();
+  for (const [name, entries] of definitions) {
+    for (const entry of entries) {
+      if (entry.scope === ":root") base.set(name, entry);
+      else {
+        if (!scopes.has(entry.scope)) scopes.set(entry.scope, new Map());
+        scopes.get(entry.scope).set(name, entry);
+      }
+    }
+  }
+  for (const name of Object.keys(tokenContract.tokens)) {
+    if (!base.has(name)) diagnostics.push({ rule: "missing-token", file: config.dsDir, line: 1, column: 1, message: `Define ${name} in :root using the project's chosen value.` });
+  }
+  const emitted = new Set();
+  function report(rule, name, entry, message) {
+    const key = `${rule}:${name}:${entry.file}:${entry.line}:${message}`;
+    if (emitted.has(key)) return;
+    emitted.add(key);
+    diagnostics.push({ rule, ...entry, message });
+  }
+  const effectiveScopes = [base, ...[...scopes.values()].map((overrides) => new Map([...base, ...overrides]))];
+  for (const scope of effectiveScopes) {
+    const cache = new Map();
+    function resolveAlias(name, chain = []) {
+      if (cache.has(name)) return cache.get(name);
+      const entry = scope.get(name);
+      if (!entry) return undefined;
+      if (chain.includes(name)) {
+        report("token-cycle", name, entry, `Cyclic token alias: ${[...chain, name].join(" -> ")}`);
+        return undefined;
+      }
+      const resolvedReferences = new Map();
+      for (const ref of references(entry.value)) {
+        if (!isSharedToken(ref.name)) report("token-name", name, entry, `${name} references ${ref.name}, which does not follow ADS's fixed token naming contract.`);
+        if (!scope.has(ref.name) && !ref.fallback) report("token-reference", name, entry, `${name} references undefined ${ref.name}.`);
+        else if (scope.has(ref.name)) resolvedReferences.set(ref.name, resolveAlias(ref.name, [...chain, name]));
+      }
+      const parsed = valueParser(entry.value).nodes.filter((node) => node.type !== "space" && node.type !== "comment");
+      if (parsed.length === 1 && parsed[0].type === "function" && parsed[0].value === "var") {
+        const ref = references(entry.value)[0];
+        if (ref && scope.has(ref.name)) {
+          cache.set(name, resolvedReferences.get(ref.name));
+          return cache.get(name);
+        }
+        if (ref?.fallback) {
+          const comma = parsed[0].nodes.findIndex((node) => node.type === "div" && node.value === ",");
+          const fallback = valueParser.stringify(parsed[0].nodes.slice(comma + 1)).trim();
+          cache.set(name, fallback);
+          return fallback;
+        }
+        return undefined;
+      }
+      cache.set(name, entry.value);
+      return entry.value;
+    }
+    for (const [name, entry] of scope) {
+      const resolved = resolveAlias(name);
+      const type = tokenContract.tokens[name]?.type;
+      if (type && resolved !== undefined && !matchesType(resolved, type)) report("token-type", name, entry, `${name} expects ${type}; found ${resolved}.`);
+    }
+  }
+  return {
+    contractVersion: tokenContract.version,
+    tokens: [...definitions].sort(([a], [b]) => a.localeCompare(b)).map(([name, entries]) => ({ name, ...tokenContract.tokens[name], definitions: entries })),
+    diagnostics,
+  };
+}

package/dist/ui-framework.mjs

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+
+const modules = new Set(["react", "preact", "preact/compat", "preact/jsx-runtime"]);
+
+/** Init checks explicit JSX choices without replacing the project's compiler. */
+export function assertFrameworkCompiler(root, framework) {
+  const visited = new Set();
+  function inspect(file) {
+    file = path.resolve(file);
+    if (visited.has(file)) return;
+    visited.add(file);
+    const parsed = ts.readConfigFile(file, ts.sys.readFile);
+    if (parsed.error) throw new Error(`Cannot read ${path.relative(root, file)}: ${ts.flattenDiagnosticMessageText(parsed.error.messageText, "\n")}`);
+    const config = ts.parseJsonConfigFileContent(parsed.config, ts.sys, path.dirname(file));
+    const { jsx, jsxImportSource } = config.options;
+    const runtime = jsxImportSource ?? ([ts.JsxEmit.ReactJSX, ts.JsxEmit.ReactJSXDev].includes(jsx) ? "react" : undefined);
+    if (["react", "preact"].includes(runtime) && runtime !== framework) {
+      throw new Error(`${path.relative(root, file)} uses ${runtime} JSX, but the selected ADS framework is ${framework}. Align the project's JSX/compiler setup before running init; ADS does not migrate frameworks.`);
+    }
+    for (const reference of config.projectReferences ?? []) inspect(ts.resolveProjectReferencePath(reference));
+  }
+  for (const name of ["tsconfig.json", "jsconfig.json"]) {
+    const file = path.join(root, name);
+    if (existsSync(file)) inspect(file);
+  }
+}
+
+/** Resolve imported UI APIs by symbol identity, including aliased namespaces.
+ * A local function named h/createElement or a shadowed import is not a UI API. */
+export function importedUiApi(expression, checker) {
+  const parts = [];
+  let base = expression;
+  while (ts.isQualifiedName(base) || ts.isPropertyAccessExpression(base)) {
+    parts.unshift((base.right ?? base.name).text);
+    base = base.left ?? base.expression;
+  }
+  if (!ts.isIdentifier(base)) return null;
+  for (const declaration of checker.getSymbolAtLocation(base)?.declarations ?? []) {
+    if (ts.isImportSpecifier(declaration) && modules.has(declaration.parent.parent.parent.moduleSpecifier.text)) {
+      return { name: [(declaration.propertyName ?? declaration.name).text, ...parts].join("."), module: declaration.parent.parent.parent.moduleSpecifier.text };
+    }
+    if (parts.length && (ts.isNamespaceImport(declaration) || ts.isImportClause(declaration))) {
+      const imported = ts.isNamespaceImport(declaration) ? declaration.parent.parent : declaration.parent;
+      if (modules.has(imported.moduleSpecifier.text)) return { name: parts.join("."), module: imported.moduleSpecifier.text };
+    }
+  }
+  return null;
+}
+
+export function importedUiName(expression, checker) {
+  return importedUiApi(expression, checker)?.name ?? null;
+}
+
+export function uiOperation(expression, checker) {
+  const name = importedUiName(expression, checker);
+  return name === "h" ? "createElement" : name;
+}

package/dist/units.mjs

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { isInside } from "./config.mjs";
+import { importResolver } from "./boundaries.mjs";
+import { isProjectDocument, projectGuideFiles } from "./project-documents.mjs";
+
+const source = /\.[cm]?[jt]sx?$/;
+const slash = file => file.replaceAll("\\", "/");
+function fail(message, file) { return Object.assign(new Error(message), { diagnostic: { rule: "mutation-unit", message, ...(file ? { file } : {}) } }); }
+
+/** Project setup and explicitly registered ADS extension/build entrypoints. */
+export function configurationFiles(options) {
+  const { root, config, sourceRoot, dsRoot } = options;
+  const files = new Set(["ds.config.json", "package.json"]);
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.isFile() && /^(?:(?:ts|js)config[^/]*\.jsonc?|(?:vite|vitest|linaria|babel|postcss|biome|oxlint)[^/]*\.(?:jsonc?|[cm]?[jt]s)|\.(?:oxlintrc|linariarc|babelrc)(?:\.json)?)$/.test(entry.name)) files.add(entry.name);
+  }
+  const resolve = importResolver(options), visited = new Set();
+  function visit(file, entrypoint = false, typeConfig = false) {
+    if (!isInside(root, file) || file === root || /(?:^|[\\/])(?:node_modules|\.git|\.ds|dist)(?:[\\/]|$)/.test(path.relative(root, file)) || visited.has(file) || !existsSync(file)) return;
+    if (!entrypoint && isInside(sourceRoot, file) && !isInside(dsRoot, file)) return;
+    if (!entrypoint && isInside(dsRoot, file) && /^(?:components|patterns|composition|tokens)[\\/]/.test(path.relative(dsRoot, file))) {
+      if (/\.[jt]sx$|\.(?:scenario|fixture)\./.test(file)) return;
+      if (source.test(file) && /(?:from\s*["'](?:react|preact|@linaria\/)|\b(?:require|import)\s*\(\s*["'](?:react|preact|@linaria\/))/.test(readFileSync(file,"utf8"))) return;
+    }
+    visited.add(file);
+    files.add(slash(path.relative(root, file)));
+    if (typeConfig) {
+      const parsed = ts.readConfigFile(file,ts.sys.readFile).config;
+      const relatives = [...(Array.isArray(parsed?.extends) ? parsed.extends : typeof parsed?.extends === "string" ? [parsed.extends] : []), ...(parsed?.references ?? []).map(item=>item.path)];
+      for (const relative of relatives) if (typeof relative === "string" && relative.startsWith(".")) {
+        const base=path.resolve(path.dirname(file),relative);
+        for (const target of [base,base+".json",path.join(base,"tsconfig.json")]) if (existsSync(target) && /\.jsonc?$/.test(target)) { visit(target,true,true); break; }
+      }
+    }
+    if (!source.test(file)) return;
+    const ast = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true);
+    function walk(node) {
+      const call = node.parent && ts.isCallExpression(node.parent) ? node.parent.expression : null;
+      const moduleCall = call && (call.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(call) && call.text === "require" || ts.isPropertyAccessExpression(call) && call.getText(ast) === "require.resolve");
+      if (ts.isStringLiteralLike(node) && (ts.isImportDeclaration(node.parent) || ts.isExportDeclaration(node.parent) || moduleCall)) {
+        for (const target of resolve(node.text, file)) if (source.test(target) || target.endsWith(".json")) visit(target);
+      }
+      ts.forEachChild(node, walk);
+    }
+    walk(ast);
+  }
+  for (const file of files) visit(path.resolve(root,file),true, /^(?:ts|js)config[^/]*\.jsonc?$/.test(file));
+  for (const plugin of config.oxlint.plugins) visit(path.resolve(root, plugin.path), true);
+  const pkg = existsSync(path.join(root, "package.json")) ? JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")) : {};
+  const scripts = new Set();
+  function script(name) {
+    if (scripts.has(name)) return;
+    scripts.add(name);
+    const command = pkg.scripts?.[name] ?? "";
+    for (const match of command.matchAll(/\b(?:npm|bun)\s+run\s+([\w:.-]+)/g)) script(match[1]);
+    for (const match of command.matchAll(/\b(?:node|bun|tsx|ts-node)\s+([^\s;&|]+\.[cm]?[jt]sx?)(?=\s|$)/g)) visit(path.resolve(root, match[1]), true);
+  }
+  for (const name of ["lint:ds", "lint:style", "lint:project", "typecheck", "build:mcp-previews", "generate:icons", ...(config.mcp.mutationChecks ?? [])]) script(name);
+  const watch = config.mcp.previewWatch;
+  if (watch) {
+    if (["npm", "bun"].includes(watch.command) && watch.args[0] === "run") script(watch.args[1]);
+    else for (const argument of [watch.command, ...watch.args]) if (/\.[cm]?[jt]sx?$/.test(argument)) visit(path.resolve(root, argument), true);
+  }
+  return files;
+}
+
+/** Ownership is derived from the existing flat/directory colocation convention. */
+export function inspectUnits(options) {
+  const { root, dsRoot, config } = options;
+  const setup = configurationFiles(options);
+  const files = [];
+  function walk(directory) {
+    if (!existsSync(directory)) return;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name.startsWith(".") || ["node_modules", "dist", "coverage"].includes(entry.name)) continue;
+      const file = path.join(directory, entry.name);
+      if (entry.isDirectory()) walk(file);
+      else if (entry.isFile()) files.push(slash(path.relative(dsRoot, file)));
+    }
+  }
+  walk(dsRoot);
+  files.sort();
+  const directoryUnits = files.filter(file => /(?:^|\/)Scenario\.[cm]?[jt]sx?$/.test(file)).map(file => slash(path.dirname(file))).sort((a, b) => b.length - a.length);
+  const flatUnits = [...new Set(files.filter(file => /^(?:components|patterns|composition)\//.test(file) && source.test(file) && !directoryUnits.some(directory => file.startsWith(directory + "/"))).map(file => {
+    const base = path.basename(file).split(".")[0];
+    return slash(path.join(path.dirname(file), base));
+  }))].sort((a, b) => b.length - a.length);
+  const publicEntry = slash(path.relative(dsRoot, path.join(dsRoot, config.publicEntry)));
+  const tokenDir = slash(path.relative(dsRoot, path.join(dsRoot, config.tokenDir)));
+  function owner(relative) {
+    const projectFile = slash(path.relative(root, path.resolve(dsRoot, relative)));
+    if (setup.has(projectFile)) return "configuration";
+    if (isProjectDocument(projectFile)) return "documentation";
+    if (!isInside(dsRoot, path.resolve(dsRoot, relative))) return null;
+    if (relative === publicEntry) return null; // Controlled re-export bookkeeping.
+    if (relative.startsWith(tokenDir + "/")) return "tokens";
+    if (relative.startsWith("assets/")) return relative.split("/").length > 2 ? relative.split("/").slice(0, 2).join("/") : "assets";
+    if (!relative.includes("/")) return /(?:\.(?:md|txt)$|^LICENSE$)/i.test(relative) ? "documentation" : "foundation";
+    if (!/^(?:components|patterns|composition)\//.test(relative)) return relative.split("/")[0];
+    for (const directory of directoryUnits) if (relative.startsWith(directory + "/")) return directory;
+    for (const unit of flatUnits) if (relative.startsWith(unit + "/") || relative.startsWith(unit + ".")) return unit;
+    const base = path.basename(relative).split(".")[0];
+    return slash(path.join(path.dirname(relative), base));
+  }
+  const units = new Map();
+  units.set("configuration", { id: "configuration", kind: "configuration", files: [...setup].filter(file => existsSync(path.join(root, file))).sort() });
+  for (const id of ["foundation", "documentation", "tokens", "assets/brand", "assets/fonts"]) units.set(id, { id, kind: id.split("/")[0], files: [] });
+  units.get("documentation").files = projectGuideFiles(root);
+  for (const relative of files) {
+    const id = owner(relative);
+    if (!id) continue;
+    if (!units.has(id)) units.set(id, { id, kind: id === "tokens" ? "tokens" : id.split("/")[0], files: [] });
+    const file = slash(path.relative(root, path.join(dsRoot, relative)));
+    if (!units.get(id).files.includes(file)) units.get(id).files.push(file);
+  }
+  return { units: [...units.values()].sort((a, b) => a.id.localeCompare(b.id)), owner, publicEntry,
+    relative: file => slash(path.relative(dsRoot, path.resolve(root, file))) };
+}
+
+export function validateUnitId(unit) {
+  if (typeof unit !== "string" || unit.length > 256 || !/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(unit) || ["components", "patterns", "composition"].includes(unit)) throw fail("Select one ADS unit ID from ads_units or an unoccupied owner path following its colocation convention.");
+}
+
+/** Reject arbitrary file batches, even when every path is inside the ADS. */
+export function checkUnitFiles(options, unit, changes, inventory = inspectUnits(options), allowNew = false) {
+  validateUnitId(unit);
+  for (const change of changes) {
+    const relative = inventory.relative(change.path);
+    if (allowNew && unit === "configuration") continue; // The candidate must register every setup/extension file.
+    if (relative === inventory.publicEntry) continue;
+    if (allowNew && change.originalContent === null && (relative.startsWith(unit + "/") || relative.startsWith(unit + "."))) continue;
+    const owner = inventory.owner(relative);
+    if (owner !== unit) throw fail(`This patch targets ${unit}; ${change.path} belongs to ${owner ?? "a different ADS layer"}. Submit a separate unit patch.`, change.path);
+  }
+  return inventory;
+}
+
+/** A candidate may establish a new directory unit, but cannot capture its peers. */
+export function checkUnitCandidate(afterOptions, unit, changes, before) {
+  const after = inspectUnits(afterOptions);
+  checkUnitFiles(afterOptions, unit, changes.filter(change => change.content !== null || before.owner(before.relative(change.path)) !== unit), after);
+  for (const entry of before.units) for (const file of entry.files) {
+    if (!existsSync(path.join(afterOptions.root, file))) continue;
+    const relative = after.relative(file);
+    if (unit === "configuration" && (entry.id === "configuration" || after.owner(relative) === "configuration")) continue;
+    if (after.owner(relative) !== entry.id) throw fail("A patch cannot change ownership of existing peer units. Choose an unoccupied owner path.", file);
+  }
+  const exportChange = changes.find(change => before.relative(change.path) === before.publicEntry);
+  if (exportChange) {
+    if (!["components", "patterns"].includes(unit.split("/")[0])) throw fail("Only a component/pattern unit may update its public re-exports.", exportChange.path);
+    const current = exportChange.originalContent ?? "", proposed = exportChange.content;
+    if (proposed === null) throw fail("The shared public entry cannot be deleted.", exportChange.path);
+    const resolve = importResolver(afterOptions);
+    function unrelated(content) {
+      const file = path.join(afterOptions.dsRoot, afterOptions.config.publicEntry);
+      const ast = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true);
+      return ast.statements.filter(statement => {
+        if (!ts.isExportDeclaration(statement) || !statement.moduleSpecifier || !ts.isStringLiteralLike(statement.moduleSpecifier)) return true;
+        const targets = resolve(statement.moduleSpecifier.text, file);
+        return !targets.length || targets.some(target => !isInside(afterOptions.dsRoot, target) || after.owner(slash(path.relative(afterOptions.dsRoot, target))) !== unit);
+      }).map(statement => statement.getText(ast)).join("\n");
+    }
+    if (unrelated(current) !== unrelated(proposed)) throw fail("Public-entry patches may change only re-exports from the selected unit; preserve all other statements.", exportChange.path);
+  }
+  if (!before.units.some(entry => entry.id === unit) && !after.units.some(entry => entry.id === unit)) throw fail("The patched files do not establish the selected ADS unit.");
+}