semantifold 0.3.0 → 0.5.0

package/src/artifact-path.js

@@ -3,6 +3,7 @@
 import {hasOnlyUnicodeScalars} from "./semantic/scalars.js"
 
 const lineTerminatorPattern = /[\n\r\u2028\u2029]/u
+const portableArtifactComponentPattern = /^[A-Za-z0-9._-]+$/u
 
 /**
  * Validates filename metadata without imposing artifact-set path semantics.
@@ -14,11 +15,11 @@ export function isValidFilenameMetadata(value) {
 }
 
 /**
- * Validates a safe relative POSIX artifact path.
+ * Validates a safe relative POSIX source path while retaining Unicode filename metadata.
  * @param {unknown} value - Candidate path.
  * @returns {value is string} Whether the value is safe.
  */
-export function isSafeArtifactPath(value) {
+export function isSafeSourcePath(value) {
   if (typeof value != "string" || value.length == 0 || value.includes("\\") || value.includes("\0") ||
     !hasOnlyUnicodeScalars(value)) return false
   if (value.startsWith("/") || /^[A-Za-z]:/u.test(value)) return false
@@ -32,3 +33,47 @@ export function isSafeArtifactPath(value) {
       return codePoint != undefined && codePoint > 31 && codePoint != 127
     }))
 }
+
+/**
+ * Validates a safe portable artifact/resource path in the closed ASCII comparison domain.
+ * @param {unknown} value - Candidate path.
+ * @returns {value is string} Whether the value is safe and portably comparable.
+ */
+export function isSafeArtifactPath(value) {
+  return isSafeSourcePath(value) && value.split("/").every(part => portableArtifactComponentPattern.test(part))
+}
+
+/**
+ * Produces a conservative portable comparison key for a validated artifact path.
+ * @param {string} value - Safe relative POSIX path.
+ * @returns {string} Complete ASCII case-fold key.
+ */
+export function portableArtifactPathKey(value) {
+  return value.toLowerCase()
+}
+
+/**
+ * Finds the first unsafe, duplicate, portable case-fold, or file/directory-prefix conflict.
+ * @param {readonly string[]} paths - Ordered candidate artifact paths.
+ * @returns {{kind: "case-fold" | "duplicate" | "prefix" | "unsafe", path: string, other?: string} | null} First conflict.
+ */
+export function findPortableArtifactPathConflict(paths) {
+  /** @type {{key: string, path: string}[]} */
+  const accepted = []
+
+  for (const path of paths) {
+    if (!isSafeArtifactPath(path)) return {kind: "unsafe", path: String(path)}
+    const key = portableArtifactPathKey(path)
+
+    for (const previous of accepted) {
+      if (path == previous.path) return {kind: "duplicate", other: previous.path, path}
+      if (key == previous.key) return {kind: "case-fold", other: previous.path, path}
+      if (key.startsWith(`${previous.key}/`) || previous.key.startsWith(`${key}/`)) {
+        return {kind: "prefix", other: previous.path, path}
+      }
+    }
+    accepted.push({key, path})
+  }
+
+  return null
+}

package/src/artifacts.js

@@ -27,6 +27,9 @@ export function createGeneratedArtifactSet(candidate) {
       invalidArtifactSet("Artifact set requires a non-empty ordered artifact array.", candidate.target)
     }
     const target = candidate.target
+    const metadata = candidate.metadata === undefined
+      ? undefined
+      : snapshotMetadataObject(candidate.metadata, target)
 
     const paths = new Set()
     const directoryPaths = new Set()
@@ -102,6 +105,7 @@ export function createGeneratedArtifactSet(candidate) {
     return Object.freeze({
       artifacts: Object.freeze(artifacts),
       entry: entryPaths[0],
+      ...(metadata === undefined ? {} : {metadata}),
       schema: /** @type {const} */ ("GeneratedArtifactSet"),
       target,
       version: /** @type {const} */ (1)
@@ -113,6 +117,69 @@ export function createGeneratedArtifactSet(candidate) {
   }
 }
 
+/**
+ * Validates target-specific metadata as detached, immutable JSON.
+ * @param {unknown} value - Metadata candidate.
+ * @param {string} target - Artifact target.
+ * @returns {Readonly<Record<string, unknown>>} Metadata snapshot.
+ */
+function snapshotMetadataObject(value, target) {
+  if (!isPlainObject(value)) invalidArtifactSet("Artifact-set metadata must be a plain JSON object.", target)
+
+  return /** @type {Readonly<Record<string, unknown>>} */ (
+    deepFreeze(snapshotMetadataValue(value, target, new WeakSet())))
+}
+
+/**
+ * Recursively snapshots a JSON metadata value without retaining caller objects.
+ * @param {unknown} value - JSON candidate.
+ * @param {string} target - Artifact target.
+ * @param {WeakSet<object>} ancestors - Active object path for cycle rejection.
+ * @returns {unknown} Detached JSON value.
+ */
+function snapshotMetadataValue(value, target, ancestors) {
+  if (value === null || typeof value == "boolean") return value
+  if (typeof value == "string") {
+    if (!hasOnlyUnicodeScalars(value)) invalidArtifactSet("Artifact-set metadata contains a lone Unicode surrogate.", target)
+
+    return value
+  }
+  if (typeof value == "number") {
+    if (!Number.isFinite(value)) invalidArtifactSet("Artifact-set metadata numbers must be finite.", target)
+
+    return value
+  }
+  if (typeof value != "object") invalidArtifactSet("Artifact-set metadata must contain only JSON values.", target)
+  if (ancestors.has(value)) invalidArtifactSet("Artifact-set metadata must not contain cycles.", target)
+  ancestors.add(value)
+
+  if (Array.isArray(value)) {
+    if (!isDenseArray(value)) invalidArtifactSet("Artifact-set metadata arrays must be dense.", target)
+    /** @type {unknown[]} */
+    const result = []
+
+    for (let index = 0; index < value.length; index += 1) result.push(snapshotMetadataValue(value[index], target, ancestors))
+    ancestors.delete(value)
+
+    return result
+  }
+  if (!isPlainObject(value)) invalidArtifactSet("Artifact-set metadata must contain only plain JSON objects.", target)
+  /** @type {Record<string, unknown>} */
+  const result = {}
+
+  for (const key of Object.keys(value).sort()) {
+    Object.defineProperty(result, key, {
+      configurable: true,
+      enumerable: true,
+      value: snapshotMetadataValue(value[key], target, ancestors),
+      writable: true
+    })
+  }
+  ancestors.delete(value)
+
+  return result
+}
+
 /**
  * Validates artifact-level text, byte, or synthetic provenance.
  * @param {unknown} value - Provenance candidate.