circuitjson-toolkit 1.0.17 → 1.1.0

package/src/core/contracts/DocumentResult.mjs

@@ -0,0 +1,198 @@
+import { CircuitJsonValidationProof } from '../context/CircuitJsonValidationProof.mjs'
+import { CircuitJsonReadOnlyDocument } from '../context/CircuitJsonReadOnlyDocument.mjs'
+import { CircuitJsonSerializedInputAudit } from '../CircuitJsonSerializedInputAudit.mjs'
+import { ToolkitAsset } from './ToolkitAsset.mjs'
+import { ToolkitDiagnostic, cloneSafeValue } from './ToolkitDiagnostic.mjs'
+
+const DOCUMENT_SCHEMA = 'ecad-toolkit.document.v1'
+const EXTENSION_SCHEMA = 'ecad-toolkit.extension.v1'
+
+/**
+ * Builds canonical document result envelopes.
+ */
+export class DocumentResult {
+    /**
+     * Creates one canonical document envelope without validating its model.
+     * @param {Record<string, any>} [fields] Document fields.
+     * @returns {Record<string, any>} Canonical document result.
+     */
+    static create(fields = {}) {
+        return DocumentResult.#create(fields, false)
+    }
+
+    /**
+     * Creates the common envelope with the requested extension ownership mode.
+     * @param {Record<string, any>} fields Document fields.
+     * @param {boolean} readonlyExtensions Whether to capture immutable extensions now.
+     * @returns {Record<string, any>} Canonical document result.
+     */
+    static #create(fields, readonlyExtensions) {
+        const source = DocumentResult.#source(fields)
+        const audit = CircuitJsonSerializedInputAudit.inspect(
+            fields.model,
+            source.fileName
+        )
+        return {
+            schema: DOCUMENT_SCHEMA,
+            id: String(
+                fields.id || DocumentResult.sourceId('document', source)
+            ),
+            modelSchema: {
+                name: 'circuit-json',
+                version: '0.0.446'
+            },
+            model: Array.isArray(fields.model) ? fields.model : [],
+            source,
+            extensions: DocumentResult.extensionForSource(
+                source.format,
+                fields.extensions,
+                { readonly: readonlyExtensions }
+            ),
+            assets: Array.isArray(fields.assets)
+                ? fields.assets.map((asset) =>
+                      CircuitJsonReadOnlyDocument.protectOwnedAsset(
+                          ToolkitAsset.create(asset)
+                      )
+                  )
+                : [],
+            diagnostics: [
+                ...(Array.isArray(fields.diagnostics)
+                    ? fields.diagnostics
+                    : []),
+                ...audit.diagnostics
+            ].map((diagnostic) => ToolkitDiagnostic.create(diagnostic)),
+            statistics: {
+                ...cloneSafeValue(fields.statistics, {}),
+                ...audit.statistics
+            }
+        }
+    }
+
+    /**
+     * Creates a canonical envelope whose model is validated and immutable.
+     * @param {Record<string, any>} [fields] Document fields.
+     * @param {{ sourceReference?: object }} [runtime] Runtime-only fields.
+     * @returns {Record<string, any>} Proven canonical document result.
+     */
+    static createValidated(fields = {}, runtime = {}) {
+        const document = DocumentResult.#create(fields, true)
+        if (Object.hasOwn(runtime || {}, 'sourceReference')) {
+            Object.defineProperty(document, 'sourceReference', {
+                configurable: false,
+                enumerable: false,
+                value: runtime.sourceReference,
+                writable: false
+            })
+        }
+        return CircuitJsonValidationProof.validateAndAttach(document)
+    }
+
+    /**
+     * Creates a stable id from normalized source identity only.
+     * @param {string} prefix Id prefix.
+     * @param {Record<string, any>} source Normalized source.
+     * @returns {string} Stable source id.
+     */
+    static sourceId(prefix, source) {
+        const identity = JSON.stringify({
+            format: source.format,
+            fileName: source.fileName || '',
+            entryNames: Array.isArray(source.entryNames)
+                ? [...source.entryNames].sort()
+                : []
+        })
+        let hash = 2166136261
+        for (const character of identity) {
+            hash ^= character.codePointAt(0)
+            hash = Math.imul(hash, 16777619)
+        }
+        return `${prefix}-${(hash >>> 0).toString(16).padStart(8, '0')}`
+    }
+
+    /**
+     * Selects and normalizes the extension namespace owned by a source.
+     * @param {string} format Source format.
+     * @param {unknown} extensions Extension candidates.
+     * @param {{ readonly?: boolean }} [options] Extension ownership options.
+     * @returns {Record<string, any>} Normalized extension map.
+     */
+    static extensionForSource(format, extensions, options = {}) {
+        if (format === 'circuitjson') return {}
+        const candidate = extensions?.[format]
+        const hasCandidate = candidate && typeof candidate === 'object'
+        if (!hasCandidate) return {}
+        if (options.readonly === true && hasCandidate) {
+            return CircuitJsonReadOnlyDocument.copyReadonlyExtensionValue(
+                candidate,
+                (snapshot) =>
+                    DocumentResult.#normalizedExtension(format, snapshot)
+            )
+        }
+        const cloned = hasCandidate ? cloneSafeValue(candidate, {}) : {}
+        return DocumentResult.#normalizedExtension(format, cloned)
+    }
+
+    /**
+     * Normalizes one already-owned source namespace without another deep copy.
+     * @param {string} format Source format.
+     * @param {Record<string, any>} namespace Owned mutable namespace.
+     * @returns {Record<string, any>} Normalized extension map.
+     */
+    static #normalizedExtension(format, namespace) {
+        const metadata = namespace.$meta || {}
+        const fields = { ...namespace }
+        delete fields.$meta
+        return {
+            [format]: {
+                $meta: {
+                    schema: String(metadata.schema || EXTENSION_SCHEMA),
+                    completeness: String(metadata.completeness || 'canonical'),
+                    included: Array.isArray(metadata.included)
+                        ? metadata.included.map(String)
+                        : [],
+                    omitted: Array.isArray(metadata.omitted)
+                        ? metadata.omitted.map(String)
+                        : []
+                },
+                ...fields
+            }
+        }
+    }
+
+    /**
+     * Normalizes document source identity and type.
+     * @param {Record<string, any>} fields Document fields.
+     * @returns {Record<string, any>} Normalized source.
+     */
+    static #source(fields) {
+        const provided = cloneSafeValue(fields.source, {})
+        const fileName = DocumentResult.#fileName(
+            provided.fileName || fields.fileName
+        )
+        const format = String(
+            provided.format || fields.format || 'circuitjson'
+        ).toLowerCase()
+        const suffix = fileName.split('.').pop()
+        return {
+            ...provided,
+            format,
+            fileName,
+            fileType: String(
+                provided.fileType ||
+                    fields.fileType ||
+                    (suffix && suffix !== fileName ? suffix : 'json')
+            ).toLowerCase()
+        }
+    }
+
+    /**
+     * Normalizes path separators without resolving filesystem paths.
+     * @param {unknown} fileName File name candidate.
+     * @returns {string} Normalized source file name.
+     */
+    static #fileName(fileName) {
+        return String(fileName || '')
+            .replaceAll('\\', '/')
+            .replace(/^\.\//u, '')
+    }
+}

package/src/core/contracts/ProjectResult.mjs

@@ -0,0 +1,96 @@
+import { DocumentResult } from './DocumentResult.mjs'
+import { ToolkitAsset } from './ToolkitAsset.mjs'
+import { ToolkitDiagnostic, cloneSafeValue } from './ToolkitDiagnostic.mjs'
+
+/**
+ * Builds canonical multi-document project envelopes.
+ */
+export class ProjectResult {
+    /**
+     * Creates one canonical project result.
+     * @param {Record<string, any>} [fields] Project fields.
+     * @returns {Record<string, any>} Canonical project result.
+     */
+    static create(fields = {}) {
+        const documents = Array.isArray(fields.documents)
+            ? fields.documents
+            : []
+        const source = ProjectResult.#source(fields.source, documents)
+        const documentIds = documents.map((document) => String(document.id))
+        const id = String(
+            fields.id || DocumentResult.sourceId('project', source)
+        )
+        return {
+            schema: 'ecad-toolkit.project.v1',
+            id,
+            source,
+            documents,
+            project:
+                fields.project == null
+                    ? null
+                    : ProjectResult.#project(
+                          fields.project,
+                          id,
+                          source,
+                          documentIds
+                      ),
+            extensions: DocumentResult.extensionForSource(
+                source.format,
+                fields.extensions
+            ),
+            assets: Array.isArray(fields.assets)
+                ? fields.assets.map((asset) => ToolkitAsset.create(asset))
+                : [],
+            diagnostics: Array.isArray(fields.diagnostics)
+                ? fields.diagnostics.map((diagnostic) =>
+                      ToolkitDiagnostic.create(diagnostic)
+                  )
+                : [],
+            statistics: cloneSafeValue(fields.statistics, {})
+        }
+    }
+
+    /**
+     * Normalizes a present project descriptor to the exact common shape.
+     * @param {unknown} project Project candidate.
+     * @param {string} resultId Project-result id.
+     * @param {Record<string, any>} source Normalized project source.
+     * @param {string[]} documentIds Loaded document ids.
+     * @returns {{ id: string, name: string, format: string, documentIds: string[], relationships: object[] }} Canonical project descriptor.
+     */
+    static #project(project, resultId, source, documentIds) {
+        const provided = cloneSafeValue(project, {})
+        return {
+            id: String(provided.id || `${resultId}-project`),
+            name: String(provided.name || ''),
+            format: String(provided.format || source.format),
+            documentIds,
+            relationships: Array.isArray(provided.relationships)
+                ? provided.relationships
+                : []
+        }
+    }
+
+    /**
+     * Normalizes project source identity.
+     * @param {unknown} source Source candidate.
+     * @param {Record<string, any>[]} documents Project documents.
+     * @returns {{ format: string, entryNames: string[] } & Record<string, any>} Normalized source.
+     */
+    static #source(source, documents) {
+        const provided = cloneSafeValue(source, {})
+        const entryNames = Array.isArray(provided.entryNames)
+            ? provided.entryNames.map(String)
+            : documents
+                  .map((document) => document?.source?.fileName)
+                  .filter(Boolean)
+                  .map(String)
+        return {
+            ...provided,
+            format: String(
+                provided.format || documents[0]?.source?.format || 'circuitjson'
+            ).toLowerCase(),
+            entryNames
+        }
+    }
+}

package/src/core/contracts/RuntimeProxyBoundary.mjs

@@ -0,0 +1,48 @@
+const IS_PROXY = (() => {
+    try {
+        const runtime = globalThis.process
+        const getBuiltinModule = Object.getOwnPropertyDescriptor(
+            runtime,
+            'getBuiltinModule'
+        )?.value
+        if (typeof getBuiltinModule !== 'function') return null
+        const utilities = Reflect.apply(getBuiltinModule, runtime, [
+            'node:util'
+        ])
+        const types = Object.getOwnPropertyDescriptor(utilities, 'types')?.value
+        const detector = Object.getOwnPropertyDescriptor(
+            types,
+            'isProxy'
+        )?.value
+        return typeof detector === 'function' ? detector : null
+    } catch {
+        return null
+    }
+})()
+
+/**
+ * Rejects executable Proxy containers before descriptor-based data handling.
+ */
+export class RuntimeProxyBoundary {
+    /**
+     * Rejects a Proxy without executing its traps when the host exposes a
+     * trusted intrinsic detector. Browser message cloning remains the final
+     * boundary in hosts without that optional detector.
+     * @param {unknown} value Candidate value.
+     * @param {string} label Human-readable value label.
+     * @returns {void}
+     */
+    static assert(value, label) {
+        if (
+            IS_PROXY &&
+            value !== null &&
+            ['object', 'function'].includes(typeof value) &&
+            Reflect.apply(IS_PROXY, undefined, [value])
+        ) {
+            throw new TypeError(`${label} must not be a Proxy.`)
+        }
+    }
+}
+
+Object.freeze(RuntimeProxyBoundary.prototype)
+Object.freeze(RuntimeProxyBoundary)