@zigrivers/surface-adapter-agnostic 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ken Allred
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,15 @@
+# Surface Agnostic Adapter
+
+Framework-agnostic HTML adapter for Surface audits.
+
+## Install
+
+```bash
+npm install @zigrivers/surface-adapter-agnostic
+```
+
+See the repository README for usage and release guidance: https://github.com/zigrivers/surface#readme
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { FrameworkAdapter, SourceFileRef, ComponentMap } from '@zigrivers/surface-core/interfaces';
+import { Result, SurfaceError } from '@zigrivers/surface-core';
+
+declare const AGNOSTIC_ADAPTER_ID = "agnostic";
+interface AgnosticFrameworkAdapter extends FrameworkAdapter {
+    readonly id: typeof AGNOSTIC_ADAPTER_ID;
+    introspect(source: SourceFileRef): Promise<Result<ComponentMap, SurfaceError>>;
+}
+declare function createAgnosticAdapter(): AgnosticFrameworkAdapter;
+
+export { AGNOSTIC_ADAPTER_ID, type AgnosticFrameworkAdapter, createAgnosticAdapter };

package/dist/index.js

@@ -0,0 +1,146 @@
+// src/index.ts
+import { createSurfaceError } from "@zigrivers/surface-core";
+import { parse } from "parse5";
+var AGNOSTIC_ADAPTER_ID = "agnostic";
+var NULL_REPLACEMENT_CHARACTER = "\uFFFD";
+var SUPPORTED_EXTENSIONS = [".html", ".htm", ".xhtml"];
+var COMPONENT_ATTRIBUTES = ["data-component", "data-surface-component"];
+var FALLBACK_SELECTORS = ["html", "body", "main"];
+function createAgnosticAdapter() {
+  return {
+    id: AGNOSTIC_ADAPTER_ID,
+    supports: (file) => SUPPORTED_EXTENSIONS.some((extension) => file.toLowerCase().endsWith(extension)),
+    introspect(source) {
+      if (!isSourceFileRef(source)) {
+        return Promise.resolve(
+          err(
+            createSurfaceError("step_failed", "SourceFileRef requires string path and contents.")
+          )
+        );
+      }
+      try {
+        return Promise.resolve(ok({ entries: introspectHtml(source) }));
+      } catch (cause) {
+        return Promise.resolve(
+          err(
+            createSurfaceError("step_failed", "Failed to introspect agnostic HTML source.", {
+              cause
+            })
+          )
+        );
+      }
+    }
+  };
+}
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error) {
+  return { ok: false, error };
+}
+function isSourceFileRef(source) {
+  if (typeof source !== "object" || source === null) {
+    return false;
+  }
+  const candidate = source;
+  return typeof candidate.path === "string" && typeof candidate.contents === "string";
+}
+function introspectHtml(source) {
+  const document = parse(source.contents);
+  const entries = /* @__PURE__ */ new Map();
+  const fallbackSelectors = /* @__PURE__ */ new Set();
+  visitElements(document, (element) => {
+    if (isFallbackSelector(element.tagName)) {
+      fallbackSelectors.add(element.tagName);
+    }
+    for (const reference of componentReferencesFor(element)) {
+      const key = `${source.path}\0${reference.component}`;
+      const existing = entries.get(key);
+      entries.set(
+        key,
+        existing === void 0 ? { component: reference.component, file: source.path, selectors: [reference.selector] } : { ...existing, selectors: [.../* @__PURE__ */ new Set([...existing.selectors, reference.selector])] }
+      );
+    }
+  });
+  if (entries.size > 0) {
+    return [...entries.values()];
+  }
+  return [
+    {
+      component: "Document",
+      file: source.path,
+      selectors: FALLBACK_SELECTORS.filter((selector) => fallbackSelectors.has(selector))
+    }
+  ];
+}
+function visitElements(node, visit) {
+  const pending = [node];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (current === void 0) {
+      continue;
+    }
+    if (isElement(current)) {
+      visit(current);
+    }
+    const next = [];
+    if (isTemplateElement(current)) {
+      next.push(current.content);
+    }
+    if ("childNodes" in current) {
+      next.push(...current.childNodes);
+    }
+    for (let index = next.length - 1; index >= 0; index -= 1) {
+      const child = next[index];
+      if (child !== void 0) {
+        pending.push(child);
+      }
+    }
+  }
+}
+function isElement(node) {
+  return "tagName" in node && "attrs" in node;
+}
+function isTemplateElement(node) {
+  return isElement(node) && "content" in node;
+}
+function componentReferencesFor(element) {
+  return COMPONENT_ATTRIBUTES.flatMap((attribute) => {
+    const rawValue = getAttribute(element, attribute);
+    const component = sanitizeComponentName(rawValue);
+    if (component !== void 0) {
+      return [{ component, selector: `[${attribute}="${escapeCssString(rawValue ?? "")}"]` }];
+    }
+    return [];
+  });
+}
+function getAttribute(element, name) {
+  return element.attrs.find((attribute) => attribute.name === name)?.value;
+}
+function isFallbackSelector(tagName) {
+  return FALLBACK_SELECTORS.includes(tagName);
+}
+function sanitizeComponentName(value) {
+  const component = value === void 0 ? void 0 : normalizeNullCharacters(value).trim();
+  return component === void 0 || component.length === 0 ? void 0 : component;
+}
+function normalizeNullCharacters(value) {
+  return value.replaceAll("\0", NULL_REPLACEMENT_CHARACTER);
+}
+function escapeCssString(value) {
+  return Array.from(normalizeNullCharacters(value), (character) => {
+    const codePoint = character.codePointAt(0);
+    if (codePoint >= 1 && codePoint <= 31 || codePoint === 127) {
+      return `\\${codePoint.toString(16)} `;
+    }
+    if (character === '"' || character === "\\") {
+      return `\\${character}`;
+    }
+    return character;
+  }).join("");
+}
+export {
+  AGNOSTIC_ADAPTER_ID,
+  createAgnosticAdapter
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n  ComponentMap,\n  ComponentMapEntry,\n  FrameworkAdapter,\n  SourceFileRef,\n} from \"@zigrivers/surface-core/interfaces\";\nimport { createSurfaceError, type Result, type SurfaceError } from \"@zigrivers/surface-core\";\nimport { parse, type DefaultTreeAdapterMap } from \"parse5\";\n\nexport const AGNOSTIC_ADAPTER_ID = \"agnostic\";\n\nconst NULL_REPLACEMENT_CHARACTER = \"\\uFFFD\";\nconst SUPPORTED_EXTENSIONS = [\".html\", \".htm\", \".xhtml\"] as const;\nconst COMPONENT_ATTRIBUTES = [\"data-component\", \"data-surface-component\"] as const;\nconst FALLBACK_SELECTORS = [\"html\", \"body\", \"main\"] as const;\n\ntype ParseNode = DefaultTreeAdapterMap[\"node\"];\ntype ParseElement = DefaultTreeAdapterMap[\"element\"];\ntype ParseTemplate = DefaultTreeAdapterMap[\"template\"];\n\nexport interface AgnosticFrameworkAdapter extends FrameworkAdapter {\n  readonly id: typeof AGNOSTIC_ADAPTER_ID;\n  introspect(source: SourceFileRef): Promise<Result<ComponentMap, SurfaceError>>;\n}\n\nexport function createAgnosticAdapter(): AgnosticFrameworkAdapter {\n  return {\n    id: AGNOSTIC_ADAPTER_ID,\n    supports: (file: string) =>\n      SUPPORTED_EXTENSIONS.some((extension) => file.toLowerCase().endsWith(extension)),\n    introspect(source: SourceFileRef) {\n      if (!isSourceFileRef(source)) {\n        return Promise.resolve(\n          err(\n            createSurfaceError(\"step_failed\", \"SourceFileRef requires string path and contents.\"),\n          ),\n        );\n      }\n\n      try {\n        return Promise.resolve(ok({ entries: introspectHtml(source) }));\n      } catch (cause) {\n        return Promise.resolve(\n          err(\n            createSurfaceError(\"step_failed\", \"Failed to introspect agnostic HTML source.\", {\n              cause,\n            }),\n          ),\n        );\n      }\n    },\n  };\n}\n\nfunction ok<T>(value: T): Result<T, SurfaceError> {\n  return { ok: true, value };\n}\n\nfunction err(error: SurfaceError): Result<never, SurfaceError> {\n  return { ok: false, error };\n}\n\nfunction isSourceFileRef(source: unknown): source is SourceFileRef {\n  if (typeof source !== \"object\" || source === null) {\n    return false;\n  }\n\n  const candidate = source as { readonly path?: unknown; readonly contents?: unknown };\n\n  return typeof candidate.path === \"string\" && typeof candidate.contents === \"string\";\n}\n\nfunction introspectHtml(source: SourceFileRef): ComponentMapEntry[] {\n  const document = parse(source.contents);\n  const entries = new Map<string, ComponentMapEntry>();\n  const fallbackSelectors = new Set<string>();\n\n  visitElements(document, (element) => {\n    if (isFallbackSelector(element.tagName)) {\n      fallbackSelectors.add(element.tagName);\n    }\n\n    for (const reference of componentReferencesFor(element)) {\n      const key = `${source.path}\\0${reference.component}`;\n      const existing = entries.get(key);\n\n      entries.set(\n        key,\n        existing === undefined\n          ? { component: reference.component, file: source.path, selectors: [reference.selector] }\n          : { ...existing, selectors: [...new Set([...existing.selectors, reference.selector])] },\n      );\n    }\n  });\n\n  if (entries.size > 0) {\n    return [...entries.values()];\n  }\n\n  return [\n    {\n      component: \"Document\",\n      file: source.path,\n      selectors: FALLBACK_SELECTORS.filter((selector) => fallbackSelectors.has(selector)),\n    },\n  ];\n}\n\nfunction visitElements(node: ParseNode, visit: (element: ParseElement) => void): void {\n  const pending: ParseNode[] = [node];\n\n  while (pending.length > 0) {\n    const current = pending.pop();\n\n    if (current === undefined) {\n      continue;\n    }\n\n    if (isElement(current)) {\n      visit(current);\n    }\n\n    const next: ParseNode[] = [];\n\n    if (isTemplateElement(current)) {\n      next.push(current.content);\n    }\n\n    if (\"childNodes\" in current) {\n      next.push(...current.childNodes);\n    }\n\n    for (let index = next.length - 1; index >= 0; index -= 1) {\n      const child = next[index];\n\n      if (child !== undefined) {\n        pending.push(child);\n      }\n    }\n  }\n}\n\nfunction isElement(node: ParseNode): node is ParseElement {\n  return \"tagName\" in node && \"attrs\" in node;\n}\n\nfunction isTemplateElement(node: ParseNode): node is ParseTemplate {\n  return isElement(node) && \"content\" in node;\n}\n\nfunction componentReferencesFor(\n  element: ParseElement,\n): Array<{ readonly component: string; readonly selector: string }> {\n  return COMPONENT_ATTRIBUTES.flatMap((attribute) => {\n    const rawValue = getAttribute(element, attribute);\n    const component = sanitizeComponentName(rawValue);\n\n    if (component !== undefined) {\n      return [{ component, selector: `[${attribute}=\"${escapeCssString(rawValue ?? \"\")}\"]` }];\n    }\n\n    return [];\n  });\n}\n\nfunction getAttribute(element: ParseElement, name: string): string | undefined {\n  return element.attrs.find((attribute) => attribute.name === name)?.value;\n}\n\nfunction isFallbackSelector(tagName: string): tagName is (typeof FALLBACK_SELECTORS)[number] {\n  return FALLBACK_SELECTORS.includes(tagName as (typeof FALLBACK_SELECTORS)[number]);\n}\n\nfunction sanitizeComponentName(value: string | undefined): string | undefined {\n  const component = value === undefined ? undefined : normalizeNullCharacters(value).trim();\n\n  return component === undefined || component.length === 0 ? undefined : component;\n}\n\nfunction normalizeNullCharacters(value: string): string {\n  return value.replaceAll(\"\\0\", NULL_REPLACEMENT_CHARACTER);\n}\n\nfunction escapeCssString(value: string): string {\n  return Array.from(normalizeNullCharacters(value), (character) => {\n    const codePoint = character.codePointAt(0)!;\n\n    if ((codePoint >= 1 && codePoint <= 0x1f) || codePoint === 0x7f) {\n      return `\\\\${codePoint.toString(16)} `;\n    }\n\n    if (character === '\"' || character === \"\\\\\") {\n      return `\\\\${character}`;\n    }\n\n    return character;\n  }).join(\"\");\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@zigrivers/surface-adapter-agnostic",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "parse5": "^8.0.0",
+    "@zigrivers/surface-core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "eslint": "^9.39.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.14"
+  },
+  "description": "Framework-agnostic HTML adapter for Surface audits",
+  "license": "MIT",
+  "homepage": "https://github.com/zigrivers/surface#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zigrivers/surface.git",
+    "directory": "packages/adapters/agnostic"
+  },
+  "bugs": {
+    "url": "https://github.com/zigrivers/surface/issues"
+  },
+  "keywords": [
+    "surface",
+    "adapter",
+    "html"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:smoke": "node scripts/build-smoke.mjs",
+    "clean": "node scripts/clean.mjs",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}