@starci/hfs 4.0.10 → 4.1.0

package/runtime/scripts/hfs/slot-classify.mjs

@@ -0,0 +1,65 @@
+// slot-classify.mjs - what slot of one scope (the app root or one side) owns a path: its status, owner unit, tier, folder kind and role.
+// A scope is {manifest, repo, profile, edition, slots, byId, variants, appKind} built once by slots.mjs; every function here reads it.
+import { globExpression } from '../lib/glob.mjs';
+import { declaredSlotEnabled } from './declaration-slots.mjs';
+import { bestMatch, fillVars, matchVariants, nearestSlot } from './slot-match.mjs';
+import { cleanSlotPath } from './slot-path.mjs';
+
+/** Whether the repository of the scope holds the slot. */
+export function slotEnabled(scope, slot) {
+  // A provider slot is gated by its provider in every edition: litePresence may lift it to required, but it still
+  // exists for this repository only while a connection declares the provider.
+  if (slot.provider !== undefined) return declaredSlotEnabled(slot, scope.repo);
+  if (slot.presence !== 'opt-in') return true;
+  return declaredSlotEnabled(slot, scope.repo);
+}
+
+/** The folder kind of a file in its slot, from a named layer or kind folder. */
+function kindOf({ variant, slot, root }, p) {
+  const names = [...(slot.layers ?? []), ...(slot.kinds ?? [])];
+  if (!names.length) return null;
+  const literal = variant.segments.find((segment) => names.includes(segment));
+  if (literal) return literal;
+  const below = root ? p.slice(root.length + 1) : p;
+  return below.split('/').slice(0, -1).find((segment) => names.includes(segment)) ?? null;
+}
+
+/** The role of a file in its slot: the entry of `roles` whose file name (variables filled from the path, `*` a wildcard inside the name) matches the file's name. */
+function roleOf(slot, bindings, p) {
+  const name = p.split('/').pop();
+  for (const [role, file] of Object.entries(slot.roles ?? {})) if (globExpression(fillVars(file, bindings)).test(name)) return role;
+  return null;
+}
+
+/**
+ * status: owned | forbidden (external slot) | not-enabled (opt-in slot the repository did not declare) | ambiguous
+ * (two slots of equal specificity; a manifest gap) | no-slot (code HFS_SLOT_UNDECLARED, with the nearest slot).
+ */
+export function classifyIn(scope, input) {
+  const p = cleanSlotPath(input);
+  const { hit, ambiguous } = bestMatch(matchVariants(scope, p));
+  if (ambiguous.length) return { path: p, status: 'ambiguous', candidates: ambiguous };
+  if (!hit) return { path: p, status: 'no-slot', code: 'HFS_SLOT_UNDECLARED', nearest: nearestSlot(scope.variants, p) };
+  const { slot, root, bindings } = hit;
+  const status = (slot.presence === 'forbidden' && 'forbidden') || (slotEnabled(scope, slot) ? 'owned' : 'not-enabled');
+  const kind = kindOf(hit, p);
+  const role = roleOf(slot, bindings, p);
+  return { path: p, status, slot: slot.id, root, bindings, ...(kind ? { kind } : {}), ...(role ? { role } : {}), presence: slot.presence, tracking: slot.tracked, ...(status === 'forbidden' ? { goesTo: slot.goesTo } : {}) };
+}
+
+/** The owner unit of `p`: the most specific owner slot instance containing it (a slot's own root when it owns nothing). */
+export function ownerIn(scope, input) {
+  const p = cleanSlotPath(input);
+  const { hit } = bestMatch(matchVariants(scope, p, (s) => s.owner === true));
+  return hit ? { slot: hit.slot.id, root: hit.root, bindings: hit.bindings } : null;
+}
+
+/** The tier of `p` in the direction matrix: its slot's tier, the owner's for an inheriting slot, none for an untiered one; null when no slot owns it. */
+export function tierIn(scope, input) {
+  const c = classifyIn(scope, input);
+  if (!c.slot) return null;
+  const tier = scope.byId.get(c.slot).tier;
+  if (tier !== 'inherit') return tier;
+  const owner = ownerIn(scope, input);
+  return owner ? scope.byId.get(owner.slot).tier : 'none';
+}

package/runtime/scripts/hfs/slot-errors.mjs

@@ -0,0 +1,11 @@
+// slot-errors.mjs - the shared refusal type for HFS manifest and declaration loaders.
+export class HfsSlotsError extends Error {
+  constructor(code, message, details = {}) {
+    super(`${code}: ${message}`);
+    this.name = 'HfsSlotsError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export const fail = (code, message, details) => { throw new HfsSlotsError(code, message, details); };

package/runtime/scripts/hfs/slot-imports.mjs

@@ -0,0 +1,76 @@
+// slot-imports.mjs - whether one file of a scope (the app root or one side) may import another: the tier direction matrix, the
+// owner units, the layer order and the public entry of an owner. Cycles are a graph property of the architecture check, not of one edge.
+import { RUNTIME_KIND } from './manifest-shape.mjs';
+import { classifyIn, ownerIn, tierIn } from './slot-classify.mjs';
+
+const isEntryFile = (name) => name === 'index.ts' || name === 'index.tsx';
+
+function unownedPathProblem(from, to) {
+  for (const side of [from, to]) {
+    if (side.status === 'no-slot') return { allowed: false, reason: 'unowned', code: side.code, path: side.path, nearest: side.nearest };
+  }
+  return null;
+}
+
+function unavailableSlotProblem(from, to) {
+  for (const side of [from, to]) {
+    if (side.status !== 'owned') return { allowed: false, reason: `slot${side.status[0].toUpperCase()}${side.status.slice(1).replace(/-(.)/g, (_, c) => c.toUpperCase())}`, path: side.path, slot: side.slot };
+  }
+  return null;
+}
+
+function sameOwnerUnit(side, owner) {
+  return owner ? `${owner.slot}:${owner.root}` : `${side.slot}:${side.root}`;
+}
+
+const layerIndex = (slot, root) => (slot.layers ? slot.layers.findIndex((layer) => root.split('/').includes(layer)) : -1);
+
+function lowerLayerProblem({ manifest, profile, byId }, from, to, fromTier, toTier, fromOwner, toOwner) {
+  if (manifest.tiers[profile][fromTier].lowerLayerOnly && fromTier === toTier) {
+    const fromSlot = byId.get((fromOwner ?? from).slot);
+    const a = layerIndex(fromSlot, fromOwner?.root ?? from.root);
+    const b = layerIndex(byId.get((toOwner ?? to).slot), toOwner?.root ?? to.root);
+    if (a >= 0 && b >= 0 && b <= a) return { allowed: false, reason: 'layerOrder', fromLayer: fromSlot.layers[a], toLayer: fromSlot.layers[b] };
+  }
+  return null;
+}
+
+function privateEntryProblem({ repo, byId }, to, toOwner) {
+  if (toOwner && repo.kind !== RUNTIME_KIND) {
+    const relative = to.path === toOwner.root ? '' : to.path.slice(toOwner.root.length + 1);
+    const ownerSlot = byId.get(toOwner.slot);
+    const entry = isEntryFile(relative) || (byId.get(to.slot).entries ?? []).includes(to.path.slice(to.root.length + 1)) || (ownerSlot.tier === 'package' && relative === 'src/index.ts') || (ownerSlot.tier === 'app' && relative === 'app.module.ts');
+    if (!entry) return { allowed: false, reason: 'notPublicEntry', owner: toOwner.root, path: to.path };
+  }
+  return null;
+}
+
+/**
+ * Whether `fromPath` may import `toPath`: {allowed, reason, ...}. Reasons: sameOwner, untiered, crossApp,
+ * tierDirection, layerOrder, notPublicEntry, allowed, slotForbidden, slotNotEnabled, slotAmbiguous, and unowned (HFS_SLOT_UNDECLARED for the path no slot owns).
+ * Cycles are a graph property and belong to the architecture check, not to one edge.
+ */
+export function importAllowedIn(scope, fromPath, toPath) {
+  const from = classifyIn(scope, fromPath);
+  const to = classifyIn(scope, toPath);
+  const unowned = unownedPathProblem(from, to);
+  if (unowned) return unowned;
+  const unavailable = unavailableSlotProblem(from, to);
+  if (unavailable) return unavailable;
+  const fromTier = tierIn(scope, from.path);
+  const toTier = tierIn(scope, to.path);
+  if (fromTier === 'none' || toTier === 'none') return { allowed: true, reason: 'untiered' };
+  if (from.bindings.app !== undefined && to.bindings.app !== undefined && from.bindings.app !== to.bindings.app)
+    return { allowed: false, reason: 'crossApp', from: from.bindings.app, to: to.bindings.app };
+  const fromOwner = ownerIn(scope, from.path);
+  const toOwner = ownerIn(scope, to.path);
+  if (sameOwnerUnit(from, fromOwner) === sameOwnerUnit(to, toOwner)) return { allowed: true, reason: 'sameOwner' };
+  const { mayImport } = scope.manifest.tiers[scope.profile][fromTier] ?? {};
+  if (!mayImport?.includes(toTier)) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport: mayImport ?? [] };
+  const layerProblem = lowerLayerProblem(scope, from, to, fromTier, toTier, fromOwner, toOwner);
+  if (layerProblem) return layerProblem;
+  // A runtime owner is imported file by file (crossOwner of knowledge/hfs/runtime-slots.yaml): no public entry.
+  const privateEntry = privateEntryProblem(scope, to, toOwner);
+  if (privateEntry) return privateEntry;
+  return { allowed: true, reason: 'allowed', fromTier, toTier };
+}

package/runtime/scripts/hfs/slot-manifest-shape.mjs

@@ -0,0 +1,73 @@
+// slot-manifest-shape.mjs - the product slot manifest's schema-shaped validation.
+import { isPlainObject } from '../../engine/plain-object.mjs';
+import { byCodeUnit } from '../lib/list.mjs';
+import { ruleParamsProblems } from './rule-params-shape.mjs';
+import { APP_KIND, EDITIONS, MANIFEST_KINDS, NAME, PRESENCE, RUNTIME_KIND, SEMVER, TESTS, TRACKED, manifestKind, runtimeShapeProblems, slotProblems, tierMapProblems } from './manifest-shape.mjs';
+
+export const PROFILES = ['be', 'fe'];
+export const APP_SCOPE = 'app';
+export const SCOPES = [APP_SCOPE, ...PROFILES];
+
+/** Shape problems of a parsed manifest, in the words of modules/schemas/hfs-slots.schema.yaml. */
+function checkCoreManifestFields(m, bad) {
+  const allowed = new Set(['schema', 'kind', 'version', 'versioning', 'presenceValues', 'trackedValues', 'testValues', 'editions', 'sides', 'appKinds', 'triggerKinds', 'tiers', 'ruleParams', 'crossOwner', 'crossApp', 'slots', 'consumers', 'naming']);
+  for (const key of Object.keys(m)) if (!allowed.has(key)) bad.push(`unknown top-level key ${key}`);
+  if (!/^starci\/hfs-slots@\d+$/.test(String(m.schema))) bad.push('schema must be starci/hfs-slots@<major>');
+  if (!SEMVER.test(String(m.version))) bad.push('version must be MAJOR.MINOR.PATCH');
+  if (!isPlainObject(m.versioning) || !['patch', 'minor', 'major', 'pins'].every((k) => typeof m.versioning[k] === 'string')) bad.push('versioning needs patch, minor, major and pins text');
+  if (JSON.stringify(m.presenceValues) !== JSON.stringify(PRESENCE)) bad.push(`presenceValues must be ${PRESENCE.join(', ')}`);
+  if (JSON.stringify(m.trackedValues) !== JSON.stringify(TRACKED)) bad.push(`trackedValues must be ${TRACKED.join(', ')}`);
+  if (JSON.stringify(m.testValues) !== JSON.stringify(TESTS)) bad.push(`testValues must be ${TESTS.join(', ')}`);
+  if (JSON.stringify(m.editions) !== JSON.stringify(EDITIONS)) bad.push(`editions must be ${EDITIONS.join(', ')}`);
+}
+
+function checkSideShapes(m, bad) {
+  if (!isPlainObject(m.sides) || Object.keys(m.sides).sort(byCodeUnit).join() !== PROFILES.join()) bad.push('sides must be a map with exactly be and fe');
+  else for (const side of PROFILES) {
+    const def = m.sides[side];
+    if (!isPlainObject(def) || Object.keys(def).join() !== 'reads' || !Array.isArray(def.reads) || !def.reads.every((r) => typeof r === 'string' && /^[a-z][a-z0-9-]*\/([^/]+\/)+$/.test(r)) || new Set(def.reads).size !== def.reads.length) bad.push(`sides.${side} must be {reads: [unique <owner>/<dir>/ paths]}`);
+  }
+}
+
+function checkTriggerKinds(m, bad) {
+  if (m.triggerKinds !== undefined && (!Array.isArray(m.triggerKinds) || !m.triggerKinds.length || !m.triggerKinds.every((k) => NAME.test(String(k))) || new Set(m.triggerKinds).size !== m.triggerKinds.length)) bad.push('triggerKinds must be a non-empty list of unique names');
+}
+
+function checkProfileMaps(m, bad) {
+  for (const key of ['appKinds', 'tiers']) {
+    if (!isPlainObject(m[key])) { bad.push(`${key} must be a map with be and fe`); continue; }
+    for (const extra of Object.keys(m[key])) if (!PROFILES.includes(extra)) bad.push(`${key}.${extra} is not a profile`);
+    for (const profile of PROFILES) if (!(profile in m[key])) bad.push(`${key}.${profile} is missing`);
+  }
+}
+
+function checkAppKindAndTierShapes(m, bad) {
+  for (const profile of PROFILES) {
+    const kinds = m.appKinds?.[profile];
+    if (kinds !== undefined && (!Array.isArray(kinds) || !kinds.length || !kinds.every((k) => NAME.test(String(k))) || new Set(kinds).size !== kinds.length)) bad.push(`appKinds.${profile} must be a non-empty list of unique names`);
+    const tiers = m.tiers?.[profile];
+    if (tiers === undefined) continue;
+    bad.push(...tierMapProblems(profile, tiers));
+  }
+}
+
+function checkSlotShapes(m, bad) {
+  if (!Array.isArray(m.slots) || !m.slots.length) { bad.push('slots must be a non-empty list'); return false; }
+  m.slots.forEach((slot, index) => bad.push(...slotProblems(slot, index, APP_KIND, { appScope: APP_SCOPE, scopes: SCOPES })));
+  return true;
+}
+
+export function manifestShapeProblems(m) {
+  const bad = [];
+  if (!isPlainObject(m)) return ['the manifest is not a map'];
+  if (!MANIFEST_KINDS.includes(manifestKind(m))) return [`kind must be one of ${MANIFEST_KINDS.join(', ')}`];
+  if (manifestKind(m) === RUNTIME_KIND) return runtimeShapeProblems(m);
+  checkCoreManifestFields(m, bad);
+  checkSideShapes(m, bad);
+  checkTriggerKinds(m, bad);
+  checkProfileMaps(m, bad);
+  checkAppKindAndTierShapes(m, bad);
+  bad.push(...ruleParamsProblems(m));
+  if (!checkSlotShapes(m, bad)) return bad;
+  return bad;
+}

package/runtime/scripts/hfs/slot-match.mjs

@@ -0,0 +1,153 @@
+// slot-match.mjs - the slot path patterns of the HFS manifest compiled to regular expressions, and the matching of a path against them:
+// the variants that match it, the most specific one, and the nearest slot of an unknown path. Pure; slot-classify.mjs asks it.
+import path from 'node:path';
+import { braceVariants } from '../lib/glob.mjs';
+import { captureNames } from '../lib/i18n.mjs';
+
+const VAR = /<([A-Za-z][A-Za-z0-9-]*)>/g;
+export const varsOf = (text) => captureNames(text, VAR);
+const hasWildcard = (segment) => /[*?]/.test(segment);
+
+/** `text` with the `<name>` variables filled from `bindings` (an unbound one stays as written). */
+export function fillVars(text, bindings) {
+  const bound = (whole, name) => bindings[name] ?? whole;
+  return `${text}`.replace(VAR, bound);
+}
+
+/** Weight of one pattern segment: literal 4, literal mixed with a variable 3, a bare variable 2, a wildcard 1, `**` 0. */
+function segmentWeight(segment) {
+  if (segment === '**') return 0;
+  if (hasWildcard(segment)) return 1;
+  if (/^<[^>]+>$/.test(segment)) return 2;
+  if (segment.includes('<')) return 3;
+  return 4;
+}
+
+/** The RegExp source of one pattern segment (no separators); variables capture, and are listed in `names`. */
+function segmentSource(segment, names) {
+  let source = '', variableEnd = -1;
+  for (let i = 0; i < segment.length; i += 1) {
+    const c = segment[i];
+    if (i <= variableEnd) continue;
+    if (c === '<') {
+      variableEnd = segment.indexOf('>', i);
+      names.push(segment.slice(i + 1, variableEnd));
+      source += '([^/]+?)';
+    } else if (c === '*') source += '[^/]*';
+    else if (c === '?') source += '[^/]';
+    else source += /[.+^${}()|[\]\\]/.test(c) ? `\\${c}` : c;
+  }
+  return source;
+}
+
+/** One brace-free pattern compiled: `dir` patterns (trailing /) own everything below their root. */
+export function compileVariant(slot, pattern) {
+  const dir = pattern.endsWith('/');
+  const body = dir ? pattern.slice(0, -1) : pattern;
+  const segments = body.split('/');
+  const names = [];
+  let source = '';
+  segments.forEach((segment, index) => {
+    const last = index === segments.length - 1;
+    if (segment === '**') source += last ? '.*' : '(?:.*/)?';
+    else source += segmentSource(segment, names) + (last ? '' : '/');
+  });
+  return {
+    slot,
+    pattern,
+    dir,
+    segments,
+    names,
+    score: segments.reduce((sum, s) => sum + segmentWeight(s), 0),
+    wildcards: segments.filter(hasWildcard).length,
+    regex: new RegExp(`^(${source})${dir ? '(?:/.*)?' : ''}$`),
+    segmentRegexes: segments.map((s) => (s === '**' ? null : new RegExp(`^${segmentSource(s, [])}$`))),
+  };
+}
+
+export const variantsOf = (slot) => braceVariants(slot.path).map((pattern) => compileVariant(slot, pattern));
+
+const levenshtein = (a, b) => {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i += 1) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const held = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = held;
+    }
+  }
+  return row[b.length];
+};
+
+/** The match of `p` against one variant: its slot, root and bindings, or null (not matching, filtered out, or an app-kind slot of another kind). */
+function matchVariant(variant, p, only, appKind) {
+  if (only && !only(variant.slot)) return null;
+  const m = variant.regex.exec(p);
+  if (!m) return null;
+  const bindings = {};
+  variant.names.forEach((name, i) => { bindings[name] = m[i + 2]; });
+  if (variant.slot.appKind !== undefined && appKind.get(bindings.app) !== variant.slot.appKind) return null;
+  const root = variant.dir ? m[1] : path.posix.dirname(m[1]);
+  return { variant, slot: variant.slot, root: root === '.' ? '' : root, bindings };
+}
+
+/** Every variant matching `p`, with its root and bindings, minus app-kind slots of another kind, the most specific first. */
+export function matchVariants({ variants, appKind }, p, only) {
+  const found = [];
+  for (const variant of variants) {
+    const hit = matchVariant(variant, p, only, appKind);
+    if (hit) found.push(hit);
+  }
+  return found.sort((a, b) => b.variant.score - a.variant.score || a.variant.wildcards - b.variant.wildcards);
+}
+
+/** The single most specific match of a sorted list: {hit, ambiguous}; two slots of equal specificity are ambiguous. */
+export function bestMatch(found) {
+  if (!found.length) return { hit: null, ambiguous: [] };
+  const top = found.filter((f) => f.variant.score === found[0].variant.score && f.variant.wildcards === found[0].variant.wildcards);
+  const distinct = [...new Set(top.map((f) => f.slot.id))];
+  return distinct.length > 1 ? { hit: null, ambiguous: distinct } : { hit: top[0], ambiguous: [] };
+}
+
+/** How many leading segments of `parts` a variant accepts. */
+function acceptedDepth(variant, parts) {
+  let depth = 0;
+  while (depth < parts.length && depth < variant.segments.length) {
+    const rx = variant.segmentRegexes[depth];
+    if (rx === null || !rx.test(parts[depth])) break;
+    depth += 1;
+  }
+  return depth;
+}
+
+/** Whether `cand` is nearer to the path than `winner`: deeper, then closer in shape, then in spelling, then more specific. */
+function nearerCandidate(cand, winner) {
+  if (!winner) return true;
+  if (cand.depth !== winner.depth) return cand.depth > winner.depth;
+  if (cand.shape !== winner.shape) return cand.shape < winner.shape;
+  if (cand.distance !== winner.distance) return cand.distance < winner.distance;
+  return cand.variant.score > winner.variant.score;
+}
+
+/** The leading segments of `p` a variant accepts, and how far it got; how the nearest slot of an unknown path is found. */
+export function nearestSlot(variants, p) {
+  const parts = p.split('/');
+  let winner = null;
+  for (const variant of variants) {
+    const depth = acceptedDepth(variant, parts);
+    const expected = variant.segments[depth] ?? '';
+    const distance = levenshtein(parts[depth] ?? '', expected.replace(VAR, ''));
+    const cand = { variant, depth, shape: Math.abs(variant.segments.length - parts.length), distance };
+    if (nearerCandidate(cand, winner)) winner = cand;
+  }
+  if (!winner) return null;
+  return {
+    slot: winner.variant.slot.id,
+    pattern: winner.variant.pattern,
+    matchedDepth: winner.depth,
+    matchedPrefix: parts.slice(0, winner.depth).join('/'),
+    expectedNext: winner.variant.segments[winner.depth] ?? null,
+  };
+}

package/runtime/scripts/hfs/slot-path.mjs

@@ -0,0 +1,8 @@
+// slot-path.mjs - normalize a slot-relative path for resolver comparisons.
+import { posixPath } from '../lib/path-key.mjs';
+
+const SLASH = '/';
+const END = '$';
+const TRAILING_SLASHES = new RegExp(`${SLASH}+${END}`);
+
+export const cleanSlotPath = (value) => posixPath(value).replace(TRAILING_SLASHES, '');

package/runtime/scripts/hfs/slot-required.mjs

@@ -0,0 +1,76 @@
+// slot-required.mjs - what a scope (the app root or one side) must contain, without walking it: the files an instance of a slot
+// requires, and the paths and minimum instance counts of every required slot. A scope is the one slots.mjs builds.
+import path from 'node:path';
+import { braceVariants } from '../lib/glob.mjs';
+import { classifyIn, slotEnabled } from './slot-classify.mjs';
+import { fillVars, varsOf } from './slot-match.mjs';
+
+/** One `requires` entry of a slot placed under `root`: a leading / makes it repository-relative, the variables are filled from `bindings`. */
+function requiredEntry(entry, bindings, root) {
+  const rooted = entry.startsWith('/');
+  const filled = fillVars(rooted ? entry.slice(1) : entry, bindings);
+  return rooted || !root || root === '.' ? filled : `${root}/${filled}`;
+}
+
+/** The files and directories the instance holding `p` must contain (directories end with /); {path} entries are repo-relative. */
+export function requiredFilesIn(scope, input) {
+  const c = classifyIn(scope, input);
+  if (!c.slot) return [];
+  const slot = scope.byId.get(c.slot);
+  return (slot.requires ?? []).map((entry) => requiredEntry(entry, c.bindings, c.root));
+}
+
+function growBindings(combos, name, values) {
+  const next = [];
+  for (const combo of combos) {
+    for (const value of values) next.push({ ...combo, [name]: value });
+  }
+  combos.splice(0, combos.length, ...next);
+}
+
+const expandApps = (repo, slot) => repo.apps.filter((a) => slot.appKind === undefined || a.kind === slot.appKind);
+
+function appendRequiredVariantPaths(repo, slot, variant, paths) {
+  const names = [...new Set(varsOf(variant))];
+  const fixed = { ...slot.requiredInstances };
+  const open = names.filter((name) => name !== 'app' && !(name in fixed));
+  if (open.length) return;
+  const combos = [{}];
+  if (names.includes('app')) growBindings(combos, 'app', expandApps(repo, slot).map((app) => app.name));
+  for (const [name, values] of Object.entries(fixed)) growBindings(combos, name, values);
+  const isInstance = names.length > 0;
+  for (const bindings of combos) {
+    const target = fillVars(variant, bindings);
+    paths.push({ slot: slot.id, path: target, via: isInstance ? 'instance' : 'slot' });
+    const root = target.endsWith('/') ? target.slice(0, -1) : path.posix.dirname(target);
+    for (const entry of slot.requires ?? []) paths.push({ slot: slot.id, path: requiredEntry(entry, bindings, root), via: 'requires' });
+  }
+}
+
+function appendRequiredSlotPaths(scope, slot, paths, minimums) {
+  if (slot.presence !== 'required' || !slotEnabled(scope, slot)) return;
+  if (slot.requiredWhen === 'connections' && !scope.repo.connections.length) return;
+  if (slot.minInstances) minimums.push({ slot: slot.id, min: slot.minInstances, ...(slot.appKind ? { appKind: slot.appKind } : {}) });
+  for (const variant of braceVariants(slot.path)) appendRequiredVariantPaths(scope.repo, slot, variant, paths);
+}
+
+function uniqueRequiredPaths(paths) {
+  const seen = new Set();
+  return paths.filter((entry) => {
+    const key = `${entry.slot}|${entry.path}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * What the repository must contain, without walking it: {paths: [{slot, path, via}], minimums: [{slot, min}]}.
+ * via is slot (a fixed path), instance (a requiredInstances or app-kind root) or requires (a file an instance needs).
+ */
+export function requiredPathsIn(scope) {
+  const paths = [];
+  const minimums = [];
+  for (const slot of scope.slots) appendRequiredSlotPaths(scope, slot, paths, minimums);
+  return { paths: uniqueRequiredPaths(paths), minimums };
+}

package/runtime/scripts/hfs/slot-semantic-problems.mjs

@@ -0,0 +1,148 @@
+// slot-semantic-problems.mjs - semantic checks for the HFS slot manifest.
+import { isPlainObject } from '../../engine/plain-object.mjs';
+import { triggerProblems } from './declaration-slots.mjs';
+import { litePresenceOf, slotInEdition } from './edition-slots.mjs';
+import { manifestKind, RUNTIME_KIND, runtimeSemanticProblems } from './manifest-shape.mjs';
+import { APP_SCOPE, PROFILES } from './slot-manifest-shape.mjs';
+
+function checkAppRootSlot(slot, bad) {
+  for (const key of ['appKind', 'owner', 'layers', 'kinds', 'composedBy', 'requiredWhen', 'requiredInstances']) {
+    if (slot[key] !== undefined) bad.push(`slot ${slot.id}: an app-root slot has no ${key}`);
+  }
+  if (slot.tier !== 'none') bad.push(`slot ${slot.id}: an app-root slot has tier none`);
+}
+
+function checkSideSlot(slot, profile, manifest, bad) {
+  const tiers = manifest.tiers[profile];
+  if (slot.tier !== 'none' && slot.tier !== 'inherit' && !(slot.tier in tiers)) bad.push(`slot ${slot.id}: tier ${slot.tier} is not a ${profile} tier`);
+  if (slot.appKind !== undefined && !manifest.appKinds[profile].includes(slot.appKind)) bad.push(`slot ${slot.id}: app kind ${slot.appKind} is not a ${profile} kind`);
+  bad.push(...triggerProblems(slot, manifest.triggerKinds));
+}
+
+function claimSlotPatterns(slot, profile, claimed, bad, braceVariants) {
+  if (slot.appKind !== undefined) return;
+  for (const variant of braceVariants(slot.path)) {
+    const key = `${profile}:${variant}`;
+    if (claimed.has(key)) bad.push(`slots ${claimed.get(key)} and ${slot.id} claim the same pattern ${variant} on ${profile}`);
+    else claimed.set(key, slot.id);
+  }
+}
+
+function checkSlotProfiles(slot, manifest, claimed, bad, braceVariants) {
+  for (const profile of slot.profiles) {
+    if (profile === APP_SCOPE) checkAppRootSlot(slot, bad);
+    else checkSideSlot(slot, profile, manifest, bad);
+    claimSlotPatterns(slot, profile, claimed, bad, braceVariants);
+  }
+}
+
+function checkLitePath(slot, pathVars, varsOf, bad, braceVariants, compileVariant) {
+  if (slot.lite?.path === undefined) return;
+  for (const name of varsOf(slot.lite.path)) if (!pathVars.has(name)) bad.push(`slot ${slot.id}: lite.path binds <${name}>, which the path does not`);
+  for (const variant of braceVariants(slot.lite.path)) {
+    try { compileVariant(slot, variant); } catch (error) { bad.push(`slot ${slot.id}: lite.path ${variant} does not compile (${error.message})`); }
+  }
+}
+
+function checkNamedPathBindings(slot, pathVars, varsOf, bad) {
+  for (const name of Object.keys(slot.requiredInstances ?? {})) {
+    if (!pathVars.has(name)) bad.push(`slot ${slot.id}: requiredInstances names <${name}>, which the path does not bind`);
+  }
+  for (const file of Object.values(slot.roles ?? {})) {
+    for (const name of varsOf(file)) if (!pathVars.has(name)) bad.push(`slot ${slot.id}: roles names <${name}> in ${file}, which the path does not bind`);
+  }
+  for (const entry of slot.requires ?? []) {
+    for (const name of varsOf(entry)) if (!pathVars.has(name)) bad.push(`slot ${slot.id}: requires ${entry} uses <${name}>, which the path does not bind`);
+  }
+}
+
+function checkSlotPatternCompilation(slot, bad, braceVariants, compileVariant) {
+  for (const variant of braceVariants(slot.path)) {
+    try { compileVariant(slot, variant); } catch (error) { bad.push(`slot ${slot.id}: pattern ${variant} does not compile (${error.message})`); }
+  }
+}
+
+function checkSlotComposition(slot, manifest, bad) {
+  for (const kind of slot.composedBy ?? []) {
+    if (!slot.profiles.every((profile) => manifest.appKinds[profile].includes(kind))) bad.push(`slot ${slot.id}: composedBy names ${kind}, which is not an app kind of every profile of the slot`);
+  }
+  if (slot.layers !== undefined && slot.tier !== 'none' && !slot.profiles.every((profile) => manifest.tiers[profile][slot.tier]?.lowerLayerOnly)) bad.push(`slot ${slot.id}: layers need a lowerLayerOnly tier`);
+}
+
+function checkLiteDeclaration(slot, manifest, bad) {
+  if (!slotInEdition(manifest, slot, 'lite') && (slot.litePresence !== undefined || slot.lite !== undefined)) bad.push(`slot ${slot.id}: litePresence/lite on a slot lite never sees (editions)`);
+  if (isPlainObject(slot.litePresence) && slot.profiles.includes(APP_SCOPE)) bad.push(`slot ${slot.id}: an app-root slot takes a bare litePresence, not a per-side map`);
+  for (const profile of slot.profiles) {
+    if (litePresenceOf(slot, profile) === 'forbidden' && typeof slot.goesTo !== 'string') bad.push(`slot ${slot.id}: forbidden in lite for ${profile}, so it says where the content goes (goesTo)`);
+  }
+}
+
+function checkSlotSemantics(slot, manifest, claimed, bad, helpers) {
+  if (claimed.ids.has(slot.id)) bad.push(`slot id ${slot.id} appears twice`);
+  claimed.ids.add(slot.id);
+  const pathVars = new Set(helpers.varsOf(slot.path));
+  checkSlotProfiles(slot, manifest, claimed.patterns, bad, helpers.braceVariants);
+  if (slot.appKind !== undefined && !pathVars.has('app')) bad.push(`slot ${slot.id}: an app-kind slot binds <app> in its path`);
+  if (slot.requiredWhen !== undefined && slot.presence !== 'required') bad.push(`slot ${slot.id}: requiredWhen belongs to a required slot`);
+  checkLiteDeclaration(slot, manifest, bad);
+  checkLitePath(slot, pathVars, helpers.varsOf, bad, helpers.braceVariants, helpers.compileVariant);
+  checkNamedPathBindings(slot, pathVars, helpers.varsOf, bad);
+  checkSlotPatternCompilation(slot, bad, helpers.braceVariants, helpers.compileVariant);
+  checkSlotComposition(slot, manifest, bad);
+}
+
+/** The problem of one declared side read, or null when a slot of the side it names (or of the app root) owns the path. */
+function sideReadProblem(manifest, side, read, braceVariants) {
+  const [owner, ...rest] = read.split('/');
+  if (owner === side) return `sides.${side}.reads names ${read}, which is its own side`;
+  const ownedBySide = PROFILES.includes(owner);
+  const profile = ownedBySide ? owner : APP_SCOPE;
+  const prefix = ownedBySide ? rest.join('/') : read;
+  const owned = manifest.slots.some((slot) => slot.profiles.includes(profile) && slot.presence !== 'forbidden' && braceVariants(slot.path).some((variant) => variant.startsWith(prefix)));
+  const ownerName = ownedBySide ? owner : 'app-root';
+  return owned ? null : `sides.${side}.reads names ${read}, which no ${ownerName} slot owns`;
+}
+
+function checkSideReads(manifest, bad, braceVariants) {
+  for (const side of PROFILES) {
+    for (const read of manifest.sides[side].reads) {
+      const problem = sideReadProblem(manifest, side, read, braceVariants);
+      if (problem) bad.push(problem);
+    }
+  }
+}
+
+function checkProfileTierTargets(manifest, profile, bad) {
+  for (const [tier, def] of Object.entries(manifest.tiers[profile])) {
+    for (const target of def.mayImport) {
+      if (!(target in manifest.tiers[profile])) bad.push(`tiers.${profile}.${tier}.mayImport names ${target}, which is not a ${profile} tier`);
+    }
+  }
+}
+
+function checkProfileAppKinds(manifest, profile, bad) {
+  for (const kind of manifest.appKinds[profile]) {
+    const owners = manifest.slots.filter((slot) => slot.profiles.includes(profile) && slot.appKind === kind);
+    if (owners.length !== 1) bad.push(`${profile} app kind ${kind} must have exactly one slot (found ${owners.length})`);
+  }
+}
+
+function checkProfileMaps(manifest, bad) {
+  for (const profile of PROFILES) {
+    checkProfileTierTargets(manifest, profile, bad);
+    checkProfileAppKinds(manifest, profile, bad);
+  }
+}
+
+/** The rules a JSON Schema cannot state: unique ids, tiers named and reachable, app kinds, variables, no duplicate pattern. */
+export function manifestSemanticProblems(manifest, helpers) {
+  const bad = [];
+  const claimed = { ids: new Set(), patterns: new Map() };
+  for (const slot of manifest.slots) checkSlotSemantics(slot, manifest, claimed, bad, helpers);
+  if (manifestKind(manifest) === RUNTIME_KIND) return [...bad, ...runtimeSemanticProblems(manifest)];
+  checkSideReads(manifest, bad, helpers.braceVariants);
+  checkProfileMaps(manifest, bad);
+  const major = Number(manifest.version.split('.')[0]);
+  if (String(manifest.schema) !== `starci/hfs-slots@${major}`) bad.push(`schema ${manifest.schema} does not carry the major of version ${manifest.version}`);
+  return bad;
+}

package/runtime/scripts/hfs/slot-side-problems.mjs

@@ -0,0 +1,28 @@
+// slot-side-problems.mjs - declaration checks for one app side against the HFS manifest.
+import { optionalSlotProblems } from './declaration-slots.mjs';
+
+function sideAppKindProblems(manifest, side, apps) {
+  const bad = [];
+  for (const app of apps) if (!manifest.appKinds[side].includes(app.kind)) bad.push(`${side} app ${app.name} has kind ${app.kind}, which is not a ${side} kind (${manifest.appKinds[side].join(', ')})`);
+  return bad;
+}
+
+function requiredAppKindProblems(manifest, side, declaration) {
+  const bad = [];
+  const connections = declaration.connections ?? [];
+  for (const slot of manifest.slots) {
+    if (slot.appKind === undefined || !slot.profiles.includes(side) || slot.presence !== 'required') continue;
+    if (slot.requiredWhen === 'connections' && !connections.length) continue;
+    if (!declaration.apps.some((app) => app.kind === slot.appKind)) bad.push(`no ${side} app of kind ${slot.appKind} is declared (${slot.id} is required${slot.requiredWhen ? ' once a connection is declared' : ''})`);
+  }
+  return bad;
+}
+
+/** Problems for one side declaration, preserving the manifest's checks and their order. */
+export function sideProblems(manifest, side, declaration) {
+  const bad = sideAppKindProblems(manifest, side, declaration.apps);
+  bad.push(...optionalSlotProblems(manifest, side, declaration));
+  for (const read of declaration.reads ?? []) if (!manifest.sides[side].reads.includes(read)) bad.push(`sides.${side}.reads names ${read}; ${side} may read only ${manifest.sides[side].reads.join(', ') || 'nothing of the other side'}`);
+  bad.push(...requiredAppKindProblems(manifest, side, declaration));
+  return bad;
+}