@reqvire-org/ads 0.0.0-stage → 0.2.9

package/dist/oxlint.mjs

@@ -0,0 +1,81 @@
+import path from "node:path";
+import { defaultConfig, importViolation } from "./config.mjs";
+import { appImportViolation, showcaseImportViolation, importResolver } from "./boundaries.mjs";
+
+const schema = [{
+  type: "object",
+  properties: {
+    projectRoot: { type: "string" },
+    dsDir: { type: "string" },
+    sourceDir: { type: "string" },
+    publicAlias: { type: "string" },
+    stylesEntry: { type: "string" },
+    inlineStyleFiles: { type: "array", items: { type: "string" } },
+    configurationFiles: { type: "array", items: { type: "string" } },
+  },
+  additionalProperties: false,
+}];
+
+function options(context) {
+  const user = context.options[0] ?? {};
+  const root = path.resolve(user.projectRoot ?? process.cwd());
+  const config = { ...defaultConfig, ...user };
+  return { root, config, dsRoot: path.resolve(root, config.dsDir) };
+}
+
+export default {
+  meta: { name: "ads" },
+  rules: {
+    "showcase-import": {
+      meta: { type: "problem", schema, messages: { showcase: "Showcase code and styles are development fixtures; runtime code must not import them." } },
+      create(context) {
+        const settings = options(context);
+        const resolve = importResolver(settings);
+        const filename = path.resolve(context.getFilename());
+        function inspect(node) {
+          if (typeof node.source?.value === "string" && showcaseImportViolation(node.source.value, filename, settings, resolve)) context.report({ node: node.source, messageId: "showcase" });
+        }
+        return { ImportDeclaration: inspect, ExportNamedDeclaration: inspect, ExportAllDeclaration: inspect, ImportExpression: inspect };
+      },
+    },
+    "no-app-import": {
+      meta: { type: "problem", schema, messages: { app: "ADS implementations and showcase fixtures must not import app code. Use public ADS APIs and local fixture data." } },
+      create(context) {
+        const settings = options(context);
+        const resolve = importResolver(settings);
+        const filename = path.resolve(context.getFilename());
+        function inspect(node) {
+          if (typeof node.source?.value === "string" && appImportViolation(node.source.value, filename, settings, resolve)) context.report({ node: node.source, messageId: "app" });
+        }
+        return { ImportDeclaration: inspect, ExportNamedDeclaration: inspect, ExportAllDeclaration: inspect, ImportExpression: inspect };
+      },
+    },
+    "public-import": {
+      meta: { type: "problem", schema, messages: { public: "Import through the project's public ADS alias, not implementation paths." } },
+      create(context) {
+        const settings = options(context);
+        const resolve = importResolver(settings);
+        const filename = path.resolve(context.getFilename());
+        const buildFiles = new Set((settings.config.configurationFiles ?? []).map(file => path.resolve(settings.root,file)));
+        function inspect(node) {
+          if (typeof node.source?.value !== "string") return;
+          if (buildFiles.has(filename) && resolve(node.source.value,filename).every(file=>buildFiles.has(file))) return;
+          if (importViolation(node.source.value, filename, settings, resolve)) context.report({ node: node.source, messageId: "public" });
+        }
+        return { ImportDeclaration: inspect, ExportNamedDeclaration: inspect, ExportAllDeclaration: inspect, ImportExpression: inspect };
+      },
+    },
+    "no-inline-style": {
+      meta: { type: "problem", schema, messages: { inline: "Move visual policy into the local ADS, or document a narrow exception in inlineStyleFiles." } },
+      create(context) {
+        const { root, config } = options(context);
+        const allowed = config.inlineStyleFiles.some((file) => path.resolve(root, file) === path.resolve(context.getFilename()));
+        return {
+          JSXAttribute(node) {
+            if (!allowed && node.name.type === "JSXIdentifier" && node.name.name === "style") context.report({ node, messageId: "inline" });
+          },
+        };
+      },
+    },
+  },
+};

package/dist/preview-resources.mjs

@@ -0,0 +1,198 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import valueParser from "postcss-value-parser";
+import { isInside } from "./config.mjs";
+
+export const PREVIEW_APP_URI = "ui://ads/preview";
+export const PREVIEW_MANIFEST_URI = "ads://preview/manifest";
+export const assetUriPattern = /^ads:\/\/assets\/[a-f0-9]{64}\.[a-z0-9]+$/;
+const hash = value => createHash("sha256").update(value).digest("hex");
+const unknownResource = message => Object.assign(new Error(message), { code: "ADS_PREVIEW_NOT_FOUND" });
+const mime = file => ({ js: "text/javascript", css: "text/css", json: "application/json", svg: "image/svg+xml", woff2: "font/woff2", woff: "font/woff", ttf: "font/ttf", otf: "font/otf", png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif", wasm: "application/wasm" })[file.split(".").pop()] ?? "application/octet-stream";
+function atomic(file, bytes) {
+  mkdirSync(path.dirname(file), { recursive: true });
+  if (realpathSync(path.dirname(file)) !== path.dirname(file)) throw new Error("Preview output cannot resolve through a symlink.");
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try { writeFileSync(temporary, bytes); renameSync(temporary, file); }
+  finally { rmSync(temporary, { force: true }); }
+}
+
+/** Registry entries remain project-owned; these virtual entries normalize mount/unmount. */
+export function previewEntriesPlugin(entries, mountEntry) {
+  const ids = new Map(entries.map((entry, index) => [`ads-preview-entry:${index}`, entry]));
+  return { name: "ads-preview-resource-entries",
+    resolveId(id) { if (ids.has(id)) return `\0${id}`; },
+    load(id) {
+      const entry = ids.get(id.slice(1));
+      if (!entry) return;
+      return `import { mountScenario } from ${JSON.stringify(mountEntry)};import Scenario from ${JSON.stringify(path.resolve(entry.root, entry.file))};export const mount = container => mountScenario(Scenario,container);`;
+    },
+  };
+}
+
+/** Convert Rollup output to registered MCP resources without evaluating project code. */
+export function createPreviewResources(output, options, entries) {
+  const bundle = (Array.isArray(output) ? output : [output]).flatMap(result => result.output);
+  const original = item => Buffer.from(item.type === "chunk" ? item.code : item.source);
+  // Rollup's emitted import names include dependency hashes. Include original
+  // content too; an immutable URI must never represent two different outputs.
+  // Bump the transform version whenever emitted resource rewriting changes.
+  const uris = new Map(bundle.map(item => [item.fileName, `ads://assets/${hash(Buffer.concat([Buffer.from("ads-preview-v1\n" + item.fileName + "\n"), original(item)]))}.${item.fileName.split(".").pop()}`]));
+  const records = {};
+  const contents = new Map();
+  function reference(from, value) {
+    if (/^(?:[a-z]+:|#|\/\/)/i.test(value)) return null;
+    const file = value.startsWith("/") ? value.slice(1) : path.posix.normalize(path.posix.join(path.posix.dirname(from), value));
+    return uris.get(file) ?? null;
+  }
+  for (const item of bundle) {
+    const uri = uris.get(item.fileName);
+    const references = new Set();
+    let bytes = original(item);
+    if (item.type === "chunk") {
+      const source = ts.createSourceFile(item.fileName, item.code, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+      const replacements = [];
+      function visit(node) {
+        if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "Worker" && node.arguments?.[0]) {
+          let bundledWorker = false;
+          function workerReference(child) {
+            if (ts.isStringLiteralLike(child)) {
+              const uri = reference(item.fileName, child.text);
+              const asset = bundle.find(candidate => uris.get(candidate.fileName) === uri);
+              if (asset?.type === "asset" && mime(asset.fileName) === "text/javascript") {
+                const worker = ts.createSourceFile(asset.fileName, original(asset).toString(), ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+                if (worker.statements.some(statement => ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement) || statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword))) throw new Error("Preview workers must be self-contained IIFE output. Set Vite worker.format to iife; keep the production worker build unchanged.");
+                bundledWorker = true;
+              }
+            }
+            ts.forEachChild(child, workerReference);
+          }
+          workerReference(node.arguments[0]);
+          // Module worker fetches reject opaque sandbox origins. Vite's IIFE
+          // output is already a classic script, so adapt only its preview call.
+          const settings = node.arguments[1];
+          if (bundledWorker && settings) {
+            replacements.push([settings.getStart(source), settings.getStart(source), "{...("]);
+            replacements.push([settings.end, settings.end, '),type:"classic"}']);
+          }
+        }
+        if (ts.isStringLiteralLike(node)) {
+          const target = reference(item.fileName, node.text);
+          if (target) {
+            references.add(target);
+            if (ts.isCallExpression(node.parent) && node.parent.expression.kind === ts.SyntaxKind.ImportKeyword) {
+              replacements.push([node.parent.getStart(source), node.parent.end, `globalThis.__dsPreviewImport(${JSON.stringify(target)})`]);
+            } else replacements.push([node.getStart(source), node.end, JSON.stringify(target)]);
+          }
+        }
+        ts.forEachChild(node, visit);
+      }
+      visit(source);
+      let code = item.code;
+      for (const [start, end, replacement] of replacements.sort((a, b) => b[0] - a[0])) code = code.slice(0, start) + replacement + code.slice(end);
+      bytes = Buffer.from(code);
+    } else if (item.fileName.endsWith(".css")) {
+      const parsed = valueParser(bytes.toString());
+      parsed.walk(node => {
+        if (node.type !== "function" || node.value !== "url") return;
+        const value = valueParser.stringify(node.nodes).replace(/^["']|["']$/g, "");
+        const target = reference(item.fileName, value);
+        if (target) { references.add(target); node.nodes = [{ type: "string", quote: '"', value: target }]; }
+      });
+      bytes = Buffer.from(parsed.toString());
+    }
+    const imports = item.type === "chunk" ? item.imports.map(file => uris.get(file)).filter(Boolean) : [];
+    const dynamicImports = item.type === "chunk" ? item.dynamicImports.map(file => uris.get(file)).filter(Boolean) : [];
+    for (const dependency of [...imports, ...dynamicImports]) references.delete(dependency);
+    const styles = item.type === "chunk" ? [...item.viteMetadata?.importedCss ?? []].map(file => uris.get(file)).filter(Boolean) : [];
+    records[uri] = { mimeType: mime(item.fileName), size: bytes.length, digest: `sha256:${hash(bytes)}`, kind: item.type === "chunk" ? "module" : "asset", imports, dynamicImports, styles, references: [...references] };
+    contents.set(uri, bytes);
+  }
+  const scenarios = entries.map((entry, index) => {
+    const chunk = bundle.find(item => item.type === "chunk" && item.facadeModuleId === `\0ads-preview-entry:${index}`);
+    if (!chunk) throw new Error(`Missing compiled scenario entry: ${entry.id}`);
+    return { id: entry.id, title: entry.title, kind: entry.kind, module: uris.get(chunk.fileName) };
+  });
+  const graph = { schemaVersion: 1, framework: options.config.framework, assets: records, scenarios };
+  const revision = hash(JSON.stringify(graph));
+  validateManifest({ ...graph, revision });
+  const target = path.resolve(options.root, options.config.mcp.previewManifest ?? ".ds/preview/manifest.json");
+  const assetsRoot = path.join(path.dirname(target), "assets");
+  const assetFiles = [...contents.keys()].map(uri => path.join(assetsRoot, uri.slice("ads://assets/".length)));
+  return { assetFiles, publish(session) {
+    const encoded = JSON.stringify({ ...graph, revision, session });
+    if (Buffer.byteLength(encoded) > 2 * 1024 * 1024) throw new Error("Preview manifest exceeds the 2 MiB resource limit.");
+    const history = path.join(path.dirname(target), "history");
+    if (existsSync(target)) {
+      try {
+        const previous = readPreviewManifest(options);
+        if (previous && previous.revision !== revision) atomic(path.join(history, `${previous.revision}.json`), JSON.stringify(previous));
+      } catch { /* A successful rebuild replaces corrupt generated metadata. */ }
+    }
+    for (const [uri, bytes] of contents) atomic(path.join(assetsRoot, uri.slice("ads://assets/".length)), bytes);
+    for (const entry of entries) {
+      const descriptor = JSON.stringify({ schemaVersion: 1, manifestUri: PREVIEW_MANIFEST_URI, revision, id: entry.id });
+      atomic(path.join(options.root, entry.artifact), `<!doctype html><html><head></head><body><script type="application/json" id="ads-preview-resource">${descriptor.replaceAll("<", "\\u003c")}</script></body></html>`);
+    }
+    atomic(target, encoded);
+    const retained = existsSync(history) ? readdirSync(history).filter(name => /^[a-f0-9]{64}\.json$/.test(name)).sort((a, b) => statSync(path.join(history, b)).mtimeMs - statSync(path.join(history, a)).mtimeMs) : [];
+    const keep = new Set(contents.keys());
+    for (const file of retained.slice(0, 6)) {
+      try { for (const uri of Object.keys(readManifestFile(path.join(history, file)).assets)) keep.add(uri); }
+      catch { rmSync(path.join(history, file), { force: true }); }
+    }
+    for (const file of retained.slice(6)) rmSync(path.join(history, file));
+    for (const file of readdirSync(assetsRoot)) if (/^[a-f0-9]{64}\.[a-z0-9]+$/.test(file) && !keep.has(`ads://assets/${file}`)) rmSync(path.join(assetsRoot, file));
+  } };
+}
+
+export function readPreviewManifest(options, { verify = false } = {}) {
+  const relative = options.config.mcp.previewManifest;
+  if (!relative) return null;
+  const file = path.resolve(options.root, relative);
+  if (!existsSync(file)) return null;
+  const manifest = readManifestFile(file);
+  if (verify) for (const uri of Object.keys(manifest.assets)) readPreviewAsset(options, uri, manifest);
+  return manifest;
+}
+
+function readManifestFile(file) {
+  if (realpathSync(file) !== file || !statSync(file).isFile() || statSync(file).size > 2 * 1024 * 1024) throw new Error("Invalid preview manifest file.");
+  return validateManifest(JSON.parse(readFileSync(file, "utf8")));
+}
+
+function validateManifest(manifest) {
+  if (manifest.schemaVersion !== 1 || !["react", "preact"].includes(manifest.framework) || typeof manifest.revision !== "string" || !manifest.assets || typeof manifest.assets !== "object" || Array.isArray(manifest.assets) || !Array.isArray(manifest.scenarios)) throw new Error("Invalid preview resource manifest. Rebuild the project previews.");
+  for (const [uri, record] of Object.entries(manifest.assets)) {
+    if (!record || !assetUriPattern.test(uri) || !/^sha256:[a-f0-9]{64}$/.test(record.digest) || !["module", "asset"].includes(record.kind)
+      || !Number.isSafeInteger(record.size) || record.size < 0 || record.size > 16 * 1024 * 1024 || typeof record.mimeType !== "string"
+      || !["imports", "dynamicImports", "styles", "references"].every(key => Array.isArray(record[key]) && record[key].every(ref => Object.hasOwn(manifest.assets, ref)))) throw new Error("Invalid preview asset dependency graph.");
+  }
+  if (manifest.scenarios.some(entry => !entry || typeof entry.id !== "string" || manifest.assets[entry.module]?.kind !== "module") || new Set(manifest.scenarios.map(entry => entry.id)).size !== manifest.scenarios.length) throw new Error("Missing or duplicate scenario module in preview manifest.");
+  const { revision, session: _session, ...graph } = manifest;
+  if (hash(JSON.stringify(graph)) !== revision) throw new Error("Preview manifest integrity check failed. Rebuild previews.");
+  return manifest;
+}
+
+export function readPreviewAsset(options, uri, manifest = readPreviewManifest(options)) {
+  if (!assetUriPattern.test(uri)) throw unknownResource("Unknown preview asset resource.");
+  let record = manifest?.assets?.[uri];
+  if (!record) {
+    const history = path.join(path.dirname(path.resolve(options.root, options.config.mcp.previewManifest)), "history");
+    for (const file of existsSync(history) ? readdirSync(history).filter(name => /^[a-f0-9]{64}\.json$/.test(name)).slice(0, 6) : []) {
+      const candidate = path.join(history, file);
+      try { record = readManifestFile(candidate).assets[uri]; }
+      catch { continue; }
+      if (record) break;
+    }
+  }
+  if (!record) throw unknownResource("Unknown or expired preview asset resource. Refresh the manifest.");
+  const directory = path.join(path.dirname(path.resolve(options.root, options.config.mcp.previewManifest)), "assets");
+  const file = path.join(directory, uri.slice("ads://assets/".length));
+  if (!isInside(directory, file) || realpathSync(file) !== file || statSync(file).size > 16 * 1024 * 1024) throw new Error("Invalid preview asset file.");
+  const bytes = readFileSync(file);
+  if (bytes.length !== record.size || `sha256:${hash(bytes)}` !== record.digest) throw new Error("Preview resource does not match its successful build. Rebuild before reviewing.");
+  return { uri, mimeType: record.mimeType, ...(/^(?:text\/|application\/json|image\/svg)/.test(record.mimeType) ? { text: bytes.toString() } : { blob: bytes.toString("base64") }) };
+}

package/dist/project-documents.mjs

@@ -0,0 +1,27 @@
+import { existsSync, lstatSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+const rootNames = ["README.md", "ADS.md", "DS.md", "ARCHITECTURE.md", "Architecture.md", "GUIDE.md", "MCP.md", "CHANGELOG.md"];
+
+/** Recognize documentation ownership even before a new guide exists. */
+export function isProjectDocument(file) {
+  return rootNames.includes(file) || /^(?:docs|doc)\/.+\.md$/i.test(file) && !file.split("/").some(part => part.startsWith("."));
+}
+
+/** Shared guide discovery for MCP resources, workflow context and editable units. */
+export function projectGuideFiles(root) {
+  const files = rootNames.filter(file => existsSync(path.join(root, file)) && lstatSync(path.join(root, file)).isFile());
+  function walk(relative) {
+    const directory = path.join(root, relative);
+    if (!existsSync(directory) || !lstatSync(directory).isDirectory()) return;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name.startsWith(".")) continue;
+      const file = `${relative}/${entry.name}`;
+      if (entry.isDirectory()) walk(file);
+      else if (entry.isFile() && isProjectDocument(file)) files.push(file);
+    }
+  }
+  walk("docs");
+  walk("doc");
+  return files.sort();
+}

package/dist/public-props.mjs

@@ -0,0 +1,74 @@
+import ts from "typescript";
+import { importedUiName } from "./ui-framework.mjs";
+
+const visualName = /^(?:background(?:Color)?|color|fill|stroke|(?:\w+)?ColorToken)$/i;
+
+function propertyName(node) {
+  return node && (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) ? node.text : null;
+}
+
+function stringKeys(node, checker, seen = new Set()) {
+  if (!node || seen.has(node)) return [];
+  seen.add(node);
+  if (ts.isLiteralTypeNode(node) && ts.isStringLiteral(node.literal)) return [node.literal.text];
+  if (ts.isUnionTypeNode(node)) return node.types.flatMap((type) => stringKeys(type, checker, seen));
+  if (ts.isTypeReferenceNode(node)) return (checker.getSymbolAtLocation(node.typeName)?.declarations ?? []).flatMap((decl) => ts.isTypeAliasDeclaration(decl) ? stringKeys(decl.type, checker, seen) : []);
+  return [];
+}
+
+// Inspect locally declared exported *Props APIs without loading React at runtime.
+// Follow local aliases and inheritance, and distinguish Omit/Pick's actual keys.
+export function inspectPublicProps(source, checker, report) {
+  function inspect(node, excluded = new Set(), seen = new Set()) {
+    if (!node || seen.has(node)) return;
+    seen = new Set([...seen, node]);
+    if (ts.isPropertySignature(node)) {
+      const name = propertyName(node.name);
+      if (excluded.has(name)) return;
+      if (name === "style") report(node, "public-style-prop", "Public ADS props must omit style. Use semantic props and documented token hooks.");
+      if (visualName.test(name ?? "") && arbitraryString(node.type, new Set())) report(node, "visual-prop", "Public visual props must use semantic variants or a finite token union, not arbitrary strings.");
+      return;
+    }
+    if (ts.isTypeReferenceNode(node) || ts.isExpressionWithTypeArguments(node)) {
+      const name = ts.isTypeReferenceNode(node) ? node.typeName : node.expression;
+      const text = ts.isIdentifier(name) ? name.text : null;
+      const args = node.typeArguments ?? [];
+      if (text === "Omit" && args.length === 2) {
+        inspect(args[0], new Set([...excluded, ...stringKeys(args[1], checker)]), seen);
+        return;
+      }
+      if (text === "Pick" && args.length === 2) {
+        if (stringKeys(args[1], checker).includes("style") && !excluded.has("style")) inspect(args[0], excluded, seen);
+        return;
+      }
+      const react = importedUiName(name, checker)?.replace(/^JSX\./, "");
+      if (react && /^(?:\w*(?:HTML|SVG)Attributes|DOMAttributes|ComponentProps(?:WithRef|WithoutRef)?)$/.test(react)) {
+        if (!excluded.has("style")) report(node, "public-style-prop", 'Public ADS props inherited from React/Preact DOM attributes must omit "style".');
+        return;
+      }
+      for (const decl of checker.getSymbolAtLocation(name)?.declarations ?? []) {
+        if (ts.isTypeAliasDeclaration(decl)) inspect(decl.type, excluded, seen);
+        if (ts.isInterfaceDeclaration(decl)) inspect(decl, excluded, seen);
+      }
+      return;
+    }
+    ts.forEachChild(node, (child) => inspect(child, excluded, seen));
+  }
+  function arbitraryString(node, seen) {
+    if (!node || seen.has(node)) return false;
+    seen.add(node);
+    if ([ts.SyntaxKind.StringKeyword, ts.SyntaxKind.AnyKeyword, ts.SyntaxKind.UnknownKeyword].includes(node.kind)) return true;
+    if (ts.isTemplateLiteralTypeNode(node)) return node.templateSpans.some((span) => arbitraryString(span.type, seen));
+    if (ts.isUnionTypeNode(node)) return node.types.some((type) => arbitraryString(type, seen));
+    if (ts.isTypeReferenceNode(node)) return (checker.getSymbolAtLocation(node.typeName)?.declarations ?? []).some((decl) => ts.isTypeAliasDeclaration(decl) && arbitraryString(decl.type, seen));
+    return false;
+  }
+  const symbol = checker.getSymbolAtLocation(source);
+  for (const exported of symbol ? checker.getExportsOfModule(symbol) : []) {
+    if (!exported.name.endsWith("Props")) continue;
+    for (const decl of exported.declarations ?? []) {
+      if (ts.isTypeAliasDeclaration(decl)) inspect(decl.type);
+      if (ts.isInterfaceDeclaration(decl)) inspect(decl);
+    }
+  }
+}