@motionstudies/data 0.1.0-alpha.32 → 0.1.0-alpha.34

package/README.md

@@ -25,6 +25,28 @@ Build release candidates with `npm run build:packages`. Distribution manifests a
 
 Source workspace manifests always stay private. `npm run check:release` builds public candidates, tests their packed consumer and records the tested tarball hashes; `npm run release:dry-run` inspects the publication without writing to npm. The manual main-branch `release.yml` workflow publishes those same tarballs with public access and provenance. See [release instructions](https://github.com/emmettl/motionstudies/blob/main/docs/RELEASING.md) for bootstrap-token and trusted-publisher setup. All four shared packages are MIT-licensed; each distribution includes `LICENSE`.
 
+## Edition maintenance and layout observation
+
+These exports are introduced in coordinated release `0.1.0-alpha.33`; earlier releases do not expose them.
+
+`checkEditionBoundary` from `@motionstudies/data/edition-boundary` verifies the four
+shared registry pins, lockfile metadata, installed package identity, public exports
+and declared source imports. Pass `directories` for the edition's required source
+and worker roots, and `additionalPackages` for other packages needing the same
+exact-pin/public-export checks. `root` defaults to the working directory. The
+checker performs no installation, mutation or network access. It rejects missing
+configured directories, workspaces, shared source copies and installed links.
+`moduleReferences` from `@motionstudies/data/module-references` supplies the same
+AST-based import analysis to local policy tests; it reports nonliteral imports as
+unverifiable. Dataset, worker and publication policy remain edition-owned.
+
+`observeLayout` from `@motionstudies/web/observe-layout` measures once immediately,
+then batches resize notifications into one animation frame. Call its returned
+cleanup before removing the observed elements; it disconnects the observer and
+cancels pending work. Without ResizeObserver it still performs the initial
+measurement. The caller owns the elements, geometry, CSS variables and their
+cleanup; the helper does not choose clearance values or depend on React.
+
 ## Timetable patterns, station calls and observation windows
 
 `@motionstudies/core/domain/network-patterns` provides a transport-neutral repeated-schedule codec. `@motionstudies/web/use-pattern-network-day` lazily decodes current/adjacent chunks after verifying byte length and SHA-256; it exposes retry and drops old-source state when the manifest URL changes. Supply stable options and a stable asset resolver. Format/category options support existing edition wire contracts.

package/edition-boundary.d.mts

@@ -0,0 +1,9 @@
+export interface EditionBoundaryOptions {
+  /** Repository root; defaults to the working directory. */
+  root?: string
+  /** Required source directories, relative to root. Defaults to src and scripts. */
+  directories?: readonly string[]
+  /** Extra registry packages whose exact pins and public exports must be checked. */
+  additionalPackages?: readonly string[]
+}
+export function checkEditionBoundary(options?: EditionBoundaryOptions): Promise<void>

package/edition-boundary.mjs

@@ -0,0 +1,48 @@
+import { access, lstat, readFile, readdir, realpath } from 'node:fs/promises'
+import { builtinModules } from 'node:module'
+import { dirname, extname, relative, resolve, sep } from 'node:path'
+import { moduleReferences } from './module-references.mjs'
+
+export async function checkEditionBoundary({ root = '.', directories = ['src', 'scripts'], additionalPackages = [] } = {}) {
+  root = resolve(root)
+  const manifest = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8'))
+  const lock = JSON.parse(await readFile(resolve(root, 'package-lock.json'), 'utf8'))
+  const declared = { ...manifest.dependencies, ...manifest.devDependencies }
+  if (manifest.workspaces) throw new Error('An edition must consume installed packages, not workspaces')
+  try { await access(resolve(root, 'packages')); throw new Error('Shared package source belongs in Motion Studies') }
+  catch (error) { if (error.code !== 'ENOENT') throw error }
+  const exported = new Map()
+  for (const name of [...['core', 'data', 'three', 'web'].map(name => `@motionstudies/${name}`), ...additionalPackages]) {
+    const version = declared[name]
+    if (!/^\d+\.\d+\.\d+(?:-(?:alpha|beta|rc)\.\d+)?$/.test(version ?? '')) throw new Error(`Expected an exact registry version: ${name}`)
+    const locked = lock.packages[`node_modules/${name}`]
+    if (locked?.version !== version || !locked.resolved?.startsWith('https://registry.npmjs.org/') || !locked.integrity?.startsWith('sha512-') || locked.link) throw new Error(`Registry lock mismatch: ${name}`)
+    const installed = resolve(root, 'node_modules', name)
+    if ((await lstat(installed)).isSymbolicLink() || !(await realpath(installed)).startsWith(`${await realpath(resolve(root, 'node_modules'))}${sep}`)) throw new Error(`Shared source link: ${name}`)
+    const pkg = JSON.parse(await readFile(`${installed}/package.json`, 'utf8'))
+    if (pkg.version !== version || pkg.private === true || (name.startsWith('@motionstudies/') && pkg.private !== false)) throw new Error(`Installed release mismatch: ${name}`)
+    exported.set(name, pkg.exports)
+  }
+
+  async function visit(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const file = resolve(directory, entry.name)
+      if (entry.isDirectory()) { await visit(file); continue }
+      if (!/\.(?:[cm]?[jt]sx?|css)$/.test(file)) continue
+      for (const reference of moduleReferences(await readFile(file, 'utf8'), file)) {
+        if (reference === undefined) throw new Error(`Unverifiable module reference in ${file}`)
+        if (/^https?:/.test(reference) && extname(file) === '.css') continue
+        if (reference.startsWith('.')) {
+          const target = relative(root, resolve(dirname(file), reference))
+          if (target === '..' || target.startsWith(`..${sep}`)) throw new Error(`${file} imports outside this repository`)
+        } else {
+          if (reference.startsWith('node:') || builtinModules.includes(reference)) continue
+          const name = reference.startsWith('@') ? reference.split('/').slice(0, 2).join('/') : reference.split('/')[0]
+          if (!declared[name]) throw new Error(`Undeclared dependency ${name} in ${file}`)
+          if (exported.has(name) && !Object.hasOwn(exported.get(name), `.${reference.slice(name.length)}`)) throw new Error(`Private package import: ${reference}`)
+        }
+      }
+    }
+  }
+  for (const directory of directories) await visit(resolve(root, directory))
+}

package/module-references.d.mts

@@ -0,0 +1 @@
+export function moduleReferences(source: string, fileName: string): (string | undefined)[]

package/module-references.mjs

@@ -0,0 +1,31 @@
+import { extname } from 'node:path'
+import { parse } from '@babel/parser'
+
+/** Parse imports, re-exports, import types, side effects and dynamic imports. */
+export function moduleReferences(source, fileName) {
+  if (extname(fileName) === '.css') {
+    return [...source.matchAll(/@import\s+(?:url\(\s*)?['"]([^'"]+)['"]/g)].map((match) => match[1])
+  }
+  const references = []
+  const ast = parse(source, {
+    sourceType: 'module',
+    plugins: [['typescript', { dts: /\.d\.[cm]?ts$/.test(fileName) }], 'jsx'],
+    createImportExpressions: true,
+  })
+  function add(node) {
+    references.push(node?.type === 'StringLiteral' ? node.value : undefined)
+  }
+  function visit(node) {
+    if (!node || typeof node !== 'object') return
+    if (['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'].includes(node.type) && node.source) add(node.source)
+    else if (node.type === 'ImportExpression') add(node.source)
+    else if (node.type === 'TSImportType') add(node.argument)
+    else if (node.type === 'CallExpression' && node.callee.type === 'Identifier' && node.callee.name === 'require') add(node.arguments[0])
+    for (const value of Object.values(node)) {
+      if (Array.isArray(value)) value.forEach(visit)
+      else if (value && typeof value === 'object') visit(value)
+    }
+  }
+  visit(ast)
+  return references
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/data",
-  "version": "0.1.0-alpha.32",
+  "version": "0.1.0-alpha.34",
   "private": false,
   "type": "module",
   "description": "Offline data preparation primitives for Motion Studies.",
@@ -118,6 +118,14 @@
     "./feed-expectations": {
       "types": "./feed-expectations.d.mts",
       "import": "./feed-expectations.mjs"
+    },
+    "./module-references": {
+      "types": "./module-references.d.mts",
+      "import": "./module-references.mjs"
+    },
+    "./edition-boundary": {
+      "types": "./edition-boundary.d.mts",
+      "import": "./edition-boundary.mjs"
     }
   },
   "files": [
@@ -133,7 +141,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.32",
-    "fast-xml-parser": "5.11.2"
+    "@motionstudies/core": "0.1.0-alpha.34",
+    "fast-xml-parser": "5.11.2",
+    "@babel/parser": "7.29.9"
   }
 }