@toa.io/norm 1.0.0-alpha.307 → 1.0.0-alpha.308

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.308](https://github.com/toa-io/toa/compare/v1.0.0-alpha.307...v1.0.0-alpha.308) (2026-09-15)
+
+**Note:** Version bump only for package @toa.io/norm
+
+
+
+
+
 # [1.0.0-alpha.307](https://github.com/toa-io/toa/compare/v1.0.0-alpha.306...v1.0.0-alpha.307) (2026-09-15)
 
 **Note:** Version bump only for package @toa.io/norm

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/norm",
-  "version": "1.0.0-alpha.307",
+  "version": "1.0.0-alpha.308",
   "type": "module",
   "description": "Toa declarations normalization and validation",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,12 +21,12 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.306",
-    "@toa.io/definitions": "1.0.0-alpha.307",
+    "@toa.io/core": "1.0.0-alpha.308",
+    "@toa.io/definitions": "1.0.0-alpha.308",
     "@toa.io/generic": "1.0.0-alpha.304",
     "@toa.io/prototype": "1.0.0-alpha.301",
     "@toa.io/schemas": "1.0.0-alpha.304",
     "fast-glob": "3.3.3"
   },
-  "gitHead": "d5f4b2e97e315ba8ab657039d0407565c96e34bc"
+  "gitHead": "66eb0d54032f60e6ead9e13fd9e21fb60c611277"
 }

package/src/.component/.expand/version.js

@@ -1,22 +1,27 @@
 import { join } from 'node:path'
 import { createHash } from 'node:crypto'
 import fs from 'node:fs/promises'
+import glob from 'fast-glob'
+
+import { definition } from '../../definition.js'
 
 export async function version(manifest) {
-  manifest.version ??= await hash(manifest.path)
+  manifest.version ??= await hash(manifest)
 }
 
 /**
  * Identifies a build of a component: it becomes the tag of its image, so it must be the
- * same for the same sources and different for different ones — on any machine.
+ * same for the same sources and different for different ones — on any machine, and whichever
+ * build produced them.
  *
- * What the image excludes cannot change it: `node_modules` is in the `.dockerignore` the
- * build writes (see `operations/src/deployment/images/image.js`), so hashing it would only
- * retag an identical image after a local install.
+ * What a build leaves out cannot change it: the bridge states what no build ships, a component
+ * adds to that with `ignore` and puts one back with `!`, and `files` names what its version is
+ * made of where a build copies only some of it. Its manifest is always one of them, because
+ * what it declares is what a caller is held to.
  */
-async function hash(path) {
-  const files = (await list(path)).sort()
-  const digests = await Promise.all(files.map((file) => digest(join(path, file))))
+async function hash(manifest) {
+  const files = (await list(manifest)).sort()
+  const digests = await Promise.all(files.map((file) => digest(join(manifest.path, file))))
   const total = createHash('sha256')
 
   // the path is part of it: moving a file changes the build even if no content did
@@ -26,24 +31,48 @@ async function hash(path) {
 }
 
 /**
- * @param {string} root
- * @param {string} [path] relative
- * @param {string[]} [acc]
- * @returns {Promise<string[]>} paths relative to `root`
+ * @param {toa.norm.Component} manifest
+ * @returns {Promise<string[]>} paths relative to the component
  */
-async function list(root, path = '', acc = []) {
-  const entries = await fs.readdir(join(root, path), { withFileTypes: true })
+async function list(manifest) {
+  const files = await glob(patterns(manifest.files), {
+    cwd: manifest.path,
+    dot: true,
+    onlyFiles: true,
+    followSymbolicLinks: false,
+    ignore: await ignore(manifest)
+  })
+
+  // what a component declares is what a caller is held to, so its manifest is always one of them
+  if (!files.includes(MANIFEST) && (await exists(join(manifest.path, MANIFEST))))
+    files.push(MANIFEST)
+
+  return files
+}
 
-  for (const entry of entries) {
-    if (EXCLUDED.has(entry.name)) continue
+/** A path names what is under it, and a pattern is taken as it is. */
+function patterns(files = ['**']) {
+  return files.flatMap((file) => (file.includes('*') ? [file] : [file, file + '/**']))
+}
 
-    const relative = path === '' ? entry.name : `${path}/${entry.name}`
+async function ignore(manifest) {
+  const { module } = await definition(manifest.bridge)
+  const stated = manifest.ignore ?? []
+  const back = new Set(
+    stated.filter((pattern) => pattern[0] === '!').map((pattern) => pattern.slice(1))
+  )
 
-    if (entry.isDirectory()) await list(root, relative, acc)
-    else if (entry.isFile()) acc.push(relative)
-  }
+  return [
+    ...(module.ignore ?? []).filter((pattern) => !back.has(pattern)),
+    ...stated.filter((pattern) => pattern[0] !== '!')
+  ]
+}
 
-  return acc
+async function exists(path) {
+  return await fs
+    .access(path)
+    .then(() => true)
+    .catch(() => false)
 }
 
 async function digest(path) {
@@ -52,4 +81,4 @@ async function digest(path) {
     .digest()
 }
 
-const EXCLUDED = new Set(['node_modules', '.git'])
+const MANIFEST = 'manifest.toa.yaml'

package/src/.component/schema.yaml

@@ -34,6 +34,18 @@ properties:
   path:
     type: string
 
+  files:
+    # what this component's version is made of, where a build of it copies only some of it
+    type: array
+    items:
+      type: string
+
+  ignore:
+    # what its version is not made of, added to what the bridge states; `!` puts one of those back
+    type: array
+    items:
+      type: string
+
   locator:
     type: object
     properties:

package/src/map.js

@@ -1,21 +1,24 @@
+import { contract } from '@toa.io/core'
+
 /**
- * Every component a Context has, with the version it runs: its own, the ones its extensions
- * bring, and the ones it evicts. A map is not rendered into a workload the way variables are, and
- * an evicted component is called like any other, so it is looked up like any other.
+ * Every component a Context has, with the version it runs and the contract of that version: its
+ * own, the ones its extensions bring, and the ones it evicts. A map is not rendered into a
+ * workload the way variables are, and an evicted component is called like any other, so it is
+ * described like any other.
  *
  * @param {toa.norm.Context} context
- * @returns {Record<string, string>}
+ * @returns {Record<string, import('@toa.io/core').Contract>}
  */
 export const map = (context) => {
-  const versions = new Map()
+  const components = new Map()
 
   for (const component of context.components ?? [])
-    versions.set(component.locator.id, component.version)
+    components.set(component.locator.id, contract.component(component))
 
   // what an extension brings reaches a context as an instance of what it depends on
   for (const instances of Object.values(context.dependencies ?? {}))
     for (const { component } of instances)
-      versions.set(component.locator.id, component.version)
+      components.set(component.locator.id, contract.component(component))
 
-  return Object.fromEntries([...versions].sort(([one], [other]) => one.localeCompare(other)))
+  return Object.fromEntries([...components].sort(([one], [other]) => one.localeCompare(other)))
 }

package/types/component.d.ts

@@ -58,6 +58,10 @@ export type Entity = {
 
 type Declaration = {
   prototype?: string
+  /** what this component's version is made of; everything under it by default */
+  files?: string[]
+  /** what its version is not made of, beside what the bridge states */
+  ignore?: string[]
   namespace: string
   name: string
   version: string

package/types/context.d.ts

@@ -34,7 +34,7 @@ export interface Dependency<T = undefined> {
   component: Manifest
 }
 
-interface Context extends Declaration {
+export interface Context extends Declaration {
   runtime?: Runtime
   environment?: string
   registry?: Registry

package/types/index.d.ts

@@ -1,9 +1,15 @@
+import type { Contract } from '@toa.io/core'
+import type { Context } from './context.d.ts'
+
 export * as context from './context.d.ts'
 export * as component from './component.d.ts'
 
 export { Manifest } from './component.d.ts'
 export * as entity from './entity.d.ts'
 
+/** Every component a Context has, by id, with the contract of the version it runs. */
+export function map(context: Context): Record<string, Contract>
+
 export interface Definition {
   /** The package's name, or the reference where it has no package.json */
   name: string