@starci/hfs 4.8.0 → 4.9.1

package/runtime/scripts/gates/canon-pins.mjs

@@ -1,119 +0,0 @@
-// canon-pins.mjs - where the canon pins live and how they are read: knowledge/hfs/canon-pins.yaml (shape:
-// modules/schemas/canon-pins.schema.yaml) and the profiles bound to the canons, modules/models/code-patterns.yaml.
-// The gates read the pins here; scripts/checks/check-canon-pins.mjs is the self-check that judges them.
-import fs from 'node:fs';
-import path from 'node:path';
-import { createRequire } from 'node:module';
-import { skillRoot } from '../../engine/runtime-root.mjs';
-import { parseYaml } from '../../engine/yaml.mjs';
-import { grammarLintFor } from '../lib/grammar-lint.mjs';
-import { locateDeclaration } from '../hfs/slots.mjs';
-import { pathKey, posixPath } from '../lib/path-key.mjs';
-import { canonContentDigest, installedFiles } from './canon-digest.mjs';
-
-export const PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
-export const SCHEMA_FILE = 'modules/schemas/canon-pins.schema.yaml';
-export const PROFILES_FILE = 'modules/models/code-patterns.yaml';
-/** A missing, mismatched or unjudged installed canon remains a failing gate. */
-export const CANON_INSTALL_CODES = Object.freeze({ missing: 'CANON_INSTALL_MISSING', mismatch: 'CANON_INSTALL_MISMATCH', unjudged: 'CANON_INSTALL_UNJUDGED' });
-
-/** The parsed canon pins of the runtime at `root`. */
-export function loadPins(root = skillRoot) {
-  return parseYaml(fs.readFileSync(path.join(root, PINS_FILE), 'utf8'));
-}
-
-/** Every independently published canon binding of a profile, including each declared Grammar family. */
-export function profileCanonBindings(profile) {
-  return [
-    { binding: 'canon', canon: profile?.canon },
-    ...Object.entries(profile?.familyCanons ?? {}).map(([family, canon]) => ({ binding: `familyCanons.${family}`, family, canon })),
-  ];
-}
-
-/** The zero-based source lines that author actual profile canon versions, including named family bindings. */
-export function canonBindingVersionLines(text) {
-  const profiles = parseYaml(text)?.profiles ?? {};
-  const bindings = new Map(Object.entries(profiles).flatMap(([profile, value]) => profileCanonBindings(value)
-    .filter(row => typeof row.canon?.package === 'string' && typeof row.canon?.version === 'string')
-    .map(row => [JSON.stringify(['profiles', profile, ...row.binding.split('.')]), row.canon])));
-  const leaves = new Map(), stack = [];
-  text.split('\n').forEach((line, index) => {
-    const separator = line.indexOf(':'), field = line.slice(0, separator), key = field.trim();
-    if (separator < 0 || !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key)) return;
-    const indent = field.length - field.trimStart().length, value = line.slice(separator + 1).trimStart();
-    while (stack.length && stack.at(-1).indent >= indent) stack.pop();
-    const keys = [...stack.map(entry => entry.key), key];
-    let binding = bindings.get(JSON.stringify(keys));
-    if (key === 'version') binding = bindings.get(JSON.stringify(keys.slice(0, -1)));
-    if (binding && (key === 'version' || /^\{.*\bversion\s*:/.test(value))) leaves.set(index, { package: binding.package, version: binding.version });
-    stack.push({ key, indent });
-  });
-  return leaves;
-}
-
-/** The universal binding and the explicitly selected family's binding; no absent selection implies a family. */
-export function selectedProfileCanonBindings(profile, family) {
-  const bindings = [{ binding: 'canon', canon: profile?.canon }];
-  if (!profile?.familyCanons) return bindings;
-  const contract = grammarLintFor(family);
-  if (contract.package === null) return bindings;
-  const canon = profile.familyCanons[contract.family];
-  if (!canon || canon.package !== contract.package) {
-    throw new Error(`Grammar family ${contract.family} has no matching code-pattern canon binding for ${contract.package}`);
-  }
-  return [...bindings, { binding: `familyCanons.${contract.family}`, family: contract.family, canon }];
-}
-
-/** The package root resolved from a side's npm install, without admitting an install above the app boundary. */
-function installedPackageRoot(directory, name, bound) {
-  const top = pathKey(bound);
-  const searched = (createRequire(path.join(directory, 'package.json')).resolve.paths(name) ?? []).filter(modules => pathKey(modules).startsWith(`${top}/`));
-  for (const modules of searched) {
-    const candidate = path.join(modules, ...name.split('/'));
-    if (fs.existsSync(path.join(candidate, 'package.json'))) return fs.realpathSync(candidate);
-  }
-  return null;
-}
-
-/** Inspect one selected binding's actual installed bytes; errors remain unavailable and mismatches remain findings. */
-function inspectBinding(root, bound, pins, profile, row, out) {
-  const { canon, family } = row, side = pins[canon?.package]?.side;
-  const label = row.binding === 'canon' ? profile : `${profile}.${row.binding}`;
-  if (!canon?.package || typeof side !== 'string') { out.errors.push(`${CANON_INSTALL_CODES.unjudged} profile ${label}: canon.package ${canon?.package} has no pinned side`); return; }
-  const installed = installedPackageRoot(path.join(root, side), canon.package, bound);
-  if (!installed) { out.errors.push(`${CANON_INSTALL_CODES.missing} profile ${label}: ${canon.package} does not resolve from ${side}/ of the app; install the pinned ${canon.version}`); return; }
-  const where = posixPath(path.relative(root, installed));
-  let manifest, version, digest;
-  try {
-    manifest = JSON.parse(fs.readFileSync(path.join(installed, 'package.json'), 'utf8'));
-    version = manifest.version ?? null;
-    digest = canonContentDigest(installed, canon.contentDigest, installedFiles(installed));
-  } catch (error) { out.errors.push(`${CANON_INSTALL_CODES.unjudged} profile ${label}: ${error.code ?? 'ERROR'} ${error.message}`); return; }
-  out.checked.push({ profile: label, ...(family ? { family } : {}), package: canon.package, side, path: where, version, digest: digest.value, files: digest.files });
-  if (version !== canon.version || digest.value !== canon.contentDigest.value || digest.files !== canon.contentDigest.files) {
-    out.findings.push({ engine: 'canon', rule: 'installed-canon-mismatch', path: where, line: null,
-      message: `${canon.package} installed for ${side}/ is ${version} with ${digest.files} files digesting ${digest.value}; profile ${label} binds ${canon.version} with ${canon.contentDigest.files} files digesting ${canon.contentDigest.value} (${CANON_INSTALL_CODES.mismatch}: reinstall the pinned version from the registry)` });
-  }
-  return Object.keys(manifest.dependencies ?? {});
-}
-
-/** Judge the universal and explicitly selected family installs against their independent version/content bindings. */
-export function inspectInstalledCanons(root, { pins, profiles, bound = root }) {
-  const out = { checked: [], findings: [], errors: [] };
-  for (const [profile, value] of Object.entries(profiles)) {
-    let bindings;
-    try {
-      const declaration = value?.familyCanons ? JSON.parse(fs.readFileSync(locateDeclaration(root).file, 'utf8')) : null;
-      bindings = selectedProfileCanonBindings(value, declaration?.sides?.fe?.grammar);
-    } catch (error) { out.errors.push(`${CANON_INSTALL_CODES.unjudged} profile ${profile}: ${error.message}`); continue; }
-    const available = profileCanonBindings(value), checked = new Set();
-    for (const row of bindings) {
-      if (checked.has(row.canon?.package)) continue;
-      checked.add(row.canon?.package);
-      const dependencies = inspectBinding(root, bound, pins, profile, row, out) ?? [];
-      // A family adapter's digest does not cover its independently published implementation dependency.
-      bindings.push(...available.filter(entry => dependencies.includes(entry.canon?.package) && !checked.has(entry.canon.package)));
-    }
-  }
-  return out;
-}

package/runtime/scripts/gates/gate-input.mjs

@@ -1,98 +0,0 @@
-// gate-input.mjs - the one base, Git delta and current-input reader of a code gate and its settle observer.
-import fs from 'node:fs';
-import path from 'node:path';
-import { byCodeUnit } from '../lib/list.mjs';
-import { revParseQuery } from '../api/git/rev-parse-query.mjs';
-import { diff as gitDiff } from '../api/git/diff.mjs';
-import { lsFiles } from '../api/git/ls-files.mjs';
-import { mergeBase as mergeBaseOf } from '../api/git/merge-base.mjs';
-import { posixPath, underAny } from '../lib/path-key.mjs';
-import { sha256File } from '../../engine/digest.mjs';
-import { gateBaseAt } from '../machine/workflow-tree.mjs';
-
-/** Run a gate-owned Git query with its existing text/rename output settings and caller options. */
-const git = (call, root, args, options = {}) => call(args, { cwd: root, config: { 'core.quotepath': 'off' }, maxBuffer: 256 * 1024 * 1024, ...options });
-
-/** Return a completed query's text, or null when the native child failed; input readers reject missing text. */
-const gitText = (call, root, args) => { const r = git(call, root, args); return !r.error && r.status === 0 ? r.stdout : null; };
-export { git as gateGit, gitText as gateGitText, gateDelta };
-
-/**
- * The base commit: --base verified as a commit; else, when --root is a workflow worktree (the registry knows it, never a
- * branch-name guess), the workflow's previous checkpoint (workflow-checkpoint.mjs gateBaseAt), so only the op's own new
- * findings block; else the merge-base of HEAD with its upstream, main or master.
- */
-export function resolveGateBase(root, base = null, { workflowBase = (dir) => gateBaseAt({ env: process.env }, dir) } = {}) {
-  if (base) {
-    const sha = gitText(revParseQuery, root, ['--verify', '--quiet', `${base}^{commit}`])?.trim();
-    if (!sha) throw Object.assign(new Error(`--base ${base} is not a commit of ${root}`), { code: 'GATE_BASE_UNKNOWN' });
-    return sha;
-  }
-  const checkpoint = workflowBase(root);
-  if (checkpoint) return checkpoint;
-  for (const ref of ['@{upstream}', 'main', 'master', 'origin/HEAD']) {
-    const sha = mergeBaseOf(root, 'HEAD', ref);
-    if (sha) return sha;
-  }
-  throw Object.assign(new Error(`no base: ${root} has no upstream, main or master to measure against; pass --base`), { code: 'GATE_BASE_UNKNOWN' });
-}
-
-/**
- * The delta between the base and the working tree, relative to --root: {changed[] (existing files), added Set, deleted Set,
- * renamed Map(new -> old)}. A rename's old path counts as deleted and its new path is measured against the old path's base
- * blob, so the findings a move carries stay preexisting; untracked files are additions.
- */
-/** Files one non-rename diff status line into the delta sets. */
-const recordStatus = (kind, rel, { added, deleted, changed }) => {
-  if (kind === 'D') { deleted.add(rel); return; }
-  changed.add(rel);
-  if (kind === 'A') added.add(rel);
-};
-
-function gateDelta(root, base) {
-  const diff = gitText(gitDiff, root, ['--name-status', '-z', '--find-renames', '--relative', base]);
-  const untracked = gitText(lsFiles, root, ['--others', '--exclude-standard', '-z']);
-  if (diff === null || untracked === null) throw new Error(`the actual gate delta of ${root} could not be listed`);
-  const status = String(diff).split('\0');
-  const added = new Set(), deleted = new Set(), changed = new Set(), renamed = new Map();
-  for (let i = 0; i < status.length && status[i]; i += 1) {
-    const kind = status[i], file = status[++i];
-    if (!file) throw new Error('the gate diff has an incomplete path record');
-    const rel = posixPath(file);
-    if (kind.startsWith('R')) {
-      const to = status[++i];
-      if (!to) throw new Error('the gate rename has no destination');
-      deleted.add(rel); changed.add(posixPath(to)); renamed.set(posixPath(to), rel);
-    }
-    else recordStatus(kind, rel, { added, deleted, changed });
-  }
-  for (const file of String(untracked).split('\0').filter(Boolean)) { const rel = posixPath(file); changed.add(rel); added.add(rel); }
-  return { changed: [...changed].filter((file) => fs.existsSync(path.join(root, file))).sort(byCodeUnit), added, deleted, renamed };
-}
-
-/**
- * Read the gate's actual base, HEAD and current input bytes without preparing or running a tool. Deleted paths carry null;
- * named files extend the real delta. Settle uses the same reader against persisted placement and ownership, so a report's
- * changed list cannot manufacture an empty slice or hide a later edit.
- */
-export function gateInputSnapshot(root, base = null, files = [], owned = null) {
-  root = path.resolve(root);
-  base = resolveGateBase(root, base);
-  const head = gitText(revParseQuery, root, ['--verify', 'HEAD'])?.trim();
-  if (!head) throw new Error(`the gate HEAD of ${root} could not be resolved`);
-  const delta = gateDelta(root, base);
-  const named = files.map((file) => {
-    const rel = path.relative(root, path.resolve(root, file));
-    if (!rel || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
-      throw new Error(`gate input ${file} is not a file inside ${root}`);
-    return posixPath(rel);
-  });
-  if (owned && (!Array.isArray(owned) || !owned.length || named.some((file) => !underAny(file, owned, { dot: true }))))
-    throw new Error('the named gate inputs are outside the admitted owned scope');
-  const inputs = [...new Set([...delta.changed, ...delta.deleted, ...named])]
-    .filter((file) => !owned || underAny(file, owned, { dot: true })).sort(byCodeUnit).map((file) => {
-    const absolute = path.join(root, file);
-    return { path: file, sha256: fs.existsSync(absolute) ? sha256File(absolute) : null };
-  });
-  return { root: posixPath(root), base, head, changed: inputs.filter((file) => file.sha256 !== null).map((file) => file.path), inputs };
-}