@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/hfs/gate-threshold.mjs

@@ -2,35 +2,27 @@
 // while fewer than GATE_ERROR_LIMIT error findings remain and none of them is a hard blocker, so a release is not held back finding
 // by finding (5, 4, 3, ...) by the last few structural nits. A plaintext secret, a failed boot proof and a broken migration block at
 // any count. Every finding is still printed; only the exit code changes. Typecheck, build and the tests are not judged here.
-
 export const GATE_ERROR_LIMIT = 20;
-
 /** The limit in force: policy/quality.yaml `gate.errorLimit`, handed in by the harness CLI as STARCI_GATE_ERROR_LIMIT, else 20. */
 export function gateErrorLimit(env = process.env) {
-  const value = Number(env.STARCI_GATE_ERROR_LIMIT);
-  return Number.isInteger(value) && value > 0 ? value : GATE_ERROR_LIMIT;
+    const value = Number(env.STARCI_GATE_ERROR_LIMIT);
+    return Number.isInteger(value) && value > 0 ? value : GATE_ERROR_LIMIT;
 }
 export const GATE_THRESHOLD_RULING = 'owner ruling gate-threshold-20 2026-10-30: app check and lint pass under 20 error findings with no plaintext secret, boot proof or migration finding';
-
 /** The codes that block at any count: plaintext secrets, the boot proof, the migrations. */
 export const HARD_BLOCKERS = Object.freeze(new Set([
-  'HFS_PLAINTEXT_SECRET', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'RT_SECRET_TRACKED',
-  'STACKS_SECRET_ENV_LITERAL', 'APP_SECRET_IN_CI', 'BE_LOG_SECRET',
-  'BE_APP_BOOT_PROOF_MISSING',
-  'DB_MIGRATION_SHAPE', 'DB_MIGRATION_DESTRUCTIVE', 'LITE_DB_MIGRATION', 'BE_MIGRATION_REVERSIBLE',
+    'HFS_PLAINTEXT_SECRET', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'RT_SECRET_TRACKED',
+    'STACKS_SECRET_ENV_LITERAL', 'APP_SECRET_IN_CI', 'BE_LOG_SECRET',
+    'BE_APP_BOOT_PROOF_MISSING',
+    'DB_MIGRATION_SHAPE', 'DB_MIGRATION_DESTRUCTIVE', 'LITE_DB_MIGRATION', 'BE_MIGRATION_REVERSIBLE',
 ]));
-
-/**
- * The verdict over the error findings (each with `code`): { pass, count, hard, line }. `pass` is true when no hard blocker is
- * among them and there are fewer than GATE_ERROR_LIMIT; `line` says which, for the report.
- */
 export function gateVerdict(errors, limit = gateErrorLimit()) {
-  const hard = [...new Set(errors.map((finding) => finding.code).filter((code) => HARD_BLOCKERS.has(code)))].sort();
-  const count = errors.length;
-  const pass = hard.length === 0 && count < limit;
-  const line = count === 0 ? null
-    : hard.length > 0 ? `gate: red, ${hard.join(', ')} block${hard.length === 1 ? 's' : ''} at any count (${count} error finding(s))`
-      : pass ? `gate: green under the threshold, ${count} error finding(s) < ${limit} and no hard blocker (owner ruling gate-threshold-20); they stay listed above`
-        : `gate: red, ${count} error finding(s), the threshold is fewer than ${limit}`;
-  return { pass, count, hard, line };
+    const hard = [...new Set(errors.map((finding) => finding.code).filter((code) => code !== null && HARD_BLOCKERS.has(code)))].sort();
+    const count = errors.length;
+    const pass = hard.length === 0 && count < limit;
+    const line = count === 0 ? null
+        : hard.length > 0 ? `gate: red, ${hard.join(', ')} block${hard.length === 1 ? 's' : ''} at any count (${count} error finding(s))`
+            : pass ? `gate: green under the threshold, ${count} error finding(s) < ${limit} and no hard blocker (owner ruling gate-threshold-20); they stay listed above`
+                : `gate: red, ${count} error finding(s), the threshold is fewer than ${limit}`;
+    return { pass, count, hard, line };
 }

package/runtime/scripts/hfs/grammar-presentation.d.mts

@@ -0,0 +1,74 @@
+/** A guidance entry of a presentation topic (universal or a family's concrete one). */
+export interface PresentationGuidance {
+    id: string;
+    requirement?: string;
+    familyRequirement?: string;
+    familySource?: string;
+    [key: string]: unknown;
+}
+/** One case of a rule (universal) or of a recipe (concrete). */
+export interface PresentationCase {
+    id: string;
+    owner?: string;
+    render?: string;
+    [key: string]: unknown;
+}
+/** The family's presentation data of one topic, as parsed from the grammar playbook. */
+export interface PresentationData {
+    inherits?: string;
+    scale?: {
+        steps: {
+            id: string;
+            value?: unknown;
+        }[];
+    };
+    componentOwnership?: {
+        rows: {
+            rule: string;
+        }[];
+    };
+    recipes?: {
+        rule: string;
+        title: string;
+        cases?: PresentationCase[];
+    }[];
+    guidance?: PresentationGuidance[];
+}
+/** A universal topic: a stable relative path and the parsed document. */
+export interface PresentationTopic {
+    rel: string;
+    doc: {
+        rules?: {
+            id: string;
+            cases?: PresentationCase[];
+            [key: string]: unknown;
+        }[];
+        guidance?: PresentationGuidance[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/** The active CSS token scope, as far as font weights need it. */
+export interface TokenScope {
+    variable(name: string): {
+        value?: unknown;
+    } | null | undefined;
+}
+/** Resolve a recorded rem, px or unitless scale value at the proof's baseline root; unsupported values stay unavailable. */
+export declare const remPx: (value: unknown) => number | null;
+/** Resolve the selected family's published text weights through the active CSS token scope. */
+export declare function fontWeightsOf(guidance: PresentationGuidance | null | undefined, scope: TokenScope | null | undefined): number[];
+/**
+ * Bind supported universal presentation cases to the selected family's numerical recipes without mutation.
+ * Missing family data and incomplete coverage fail visibly rather than selecting another family.
+ * @param {object[]} knowledge - Universal topics with stable relative paths and parsed documents.
+ * @param {{ family?: string, repo?: string }} input - Explicit family or the app whose declaration selects it.
+ * @returns {{ family: string, knowledge: object[] }} Selected family and proof-ready topics with owner provenance.
+ */
+export declare function familyPresentationKnowledge(knowledge: PresentationTopic[], { family, repo }?: {
+    family?: string | null;
+    repo?: string | null;
+}): {
+    family: string;
+    knowledge: PresentationTopic[];
+};

package/runtime/scripts/hfs/grammar-presentation.mjs

@@ -6,131 +6,131 @@ import { parseYaml } from '../../engine/yaml.mjs';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { openHfs } from './slots.mjs';
 import { grammarFamilyFor } from '../lib/grammar-lint.mjs';
-
 const GRAMMARS = fileURLToPath(new URL('../../knowledge/grammars/', import.meta.url));
 const PADDING_TOPIC = 'presentation/padding.yaml';
 const TOPIC_NAMES = ['padding', 'font'];
 const REM_PX = 16;
 const TEXT_WEIGHT_NAMES = ['normal', 'medium', 'semibold'];
-
 /** The Common text-weight matrix is complete only when each public weight has one declared class. */
 function fontWeightClasses(guidance) {
-  const matrix = guidance?.familyRequirement ?? guidance?.requirement ?? '';
-  const pattern = new RegExp('`font-(' + TEXT_WEIGHT_NAMES.join('|') + ')`', 'g');
-  const names = [...String(matrix).matchAll(pattern)].map(match => match[1]);
-  if (names.length !== TEXT_WEIGHT_NAMES.length || new Set(names).size !== TEXT_WEIGHT_NAMES.length) {
-    throw new Error('Grammar font weight matrix is missing or incomplete');
-  }
-  return names;
+    const matrix = guidance?.familyRequirement ?? guidance?.requirement ?? '';
+    const pattern = new RegExp('`font-(' + TEXT_WEIGHT_NAMES.join('|') + ')`', 'g');
+    const names = [...String(matrix).matchAll(pattern)].map((match) => match[1]);
+    if (names.length !== TEXT_WEIGHT_NAMES.length || new Set(names).size !== TEXT_WEIGHT_NAMES.length) {
+        throw new Error('Grammar font weight matrix is missing or incomplete');
+    }
+    return names;
 }
-
 /** Resolve a recorded rem, px or unitless scale value at the proof's baseline root; unsupported values stay unavailable. */
 export const remPx = (value) => {
-  const match = /^(-?(?:\d+(?:\.\d+)?|\.\d+))(rem|px)?$/.exec(String(value ?? '').trim());
-  if (!match) return null;
-  const px = Number(match[1]) * (match[2] === 'px' ? 1 : REM_PX);
-  return Number.isFinite(px) ? px : null;
+    const match = /^(-?(?:\d+(?:\.\d+)?|\.\d+))(rem|px)?$/.exec(String(value ?? '').trim());
+    if (!match)
+        return null;
+    const px = Number(match[1]) * (match[2] === 'px' ? 1 : REM_PX);
+    return Number.isFinite(px) ? px : null;
 };
-
 /** Resolve the selected family's published text weights through the active CSS token scope. */
 export function fontWeightsOf(guidance, scope) {
-  const weights = fontWeightClasses(guidance).map(name => Number(scope?.variable(`--font-weight-${name}`)?.value));
-  if (weights.some(weight => !Number.isFinite(weight))) throw new Error('Grammar font weight tokens are unresolved');
-  return weights;
+    const weights = fontWeightClasses(guidance).map(name => Number(scope?.variable(`--font-weight-${name}`)?.value));
+    if (weights.some(weight => !Number.isFinite(weight)))
+        throw new Error('Grammar font weight tokens are unresolved');
+    return weights;
 }
-
 /** Missing or ambiguous family weight data cannot remove the render's weight proof. */
 function validateFontGuidance(data) {
-  const weights = (data.guidance ?? []).filter(item => item.id === 'weight');
-  if (weights.length !== 1) throw new Error('Grammar font guidance needs one concrete weight matrix');
-  fontWeightClasses(weights[0]);
+    const weights = (data.guidance ?? []).filter((item) => item.id === 'weight');
+    if (weights.length !== 1)
+        throw new Error('Grammar font guidance needs one concrete weight matrix');
+    fontWeightClasses(weights[0]);
 }
-
 /** Read the explicit family or the app declaration; CSS discovery never chooses presentation law. */
 function selectedFamily(family, repo) {
-  if (family !== null && family !== undefined) return grammarFamilyFor(family).id;
-  if (!repo) throw new Error('Presentation proof needs an explicit Grammar family or an app repository');
-  const declaration = openHfs({ root: skillRoot, repoRoot: repo }).repo;
-  return grammarFamilyFor(declaration.grammar ?? declaration.sides?.fe?.grammar).id;
+    if (family !== null && family !== undefined)
+        return grammarFamilyFor(family).id;
+    if (!repo)
+        throw new Error('Presentation proof needs an explicit Grammar family or an app repository');
+    const declaration = openHfs({ root: skillRoot, repoRoot: repo }).repo;
+    return grammarFamilyFor(declaration.grammar ?? declaration.sides?.fe?.grammar).id;
 }
-
 /** The one declared presentation owner, following only explicit inheritance and rejecting cycles. */
 function presentationOwner(family, name, seen = new Set()) {
-  if (seen.has(family)) throw new Error(`Grammar ${name} inheritance cycles at ${family}`);
-  seen.add(family);
-  const entry = grammarFamilyFor(family);
-  if (typeof entry.productComposition !== 'string' || !entry.productComposition) {
-    throw new Error(`Grammar family ${family} has no presentation playbook`);
-  }
-  const file = path.resolve(GRAMMARS, entry.productComposition);
-  const relative = path.relative(GRAMMARS, file);
-  if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`Grammar family ${family} has an invalid presentation path`);
-  const doc = parseYaml(fs.readFileSync(file, 'utf8'));
-  const data = doc?.presentation?.[name];
-  if (!data || typeof data !== 'object') throw new Error(`Grammar family ${family} has no ${name} presentation data`);
-  if (Object.hasOwn(data, 'inherits')) {
-    if (Object.keys(data).some(key => !['inherits', 'ownership', 'contract'].includes(key))) {
-      throw new Error(`Grammar family ${family} mixes inherited and replacement ${name} data`);
+    if (seen.has(family))
+        throw new Error(`Grammar ${name} inheritance cycles at ${family}`);
+    seen.add(family);
+    const entry = grammarFamilyFor(family);
+    if (typeof entry.productComposition !== 'string' || !entry.productComposition) {
+        throw new Error(`Grammar family ${family} has no presentation playbook`);
+    }
+    const file = path.resolve(GRAMMARS, entry.productComposition);
+    const relative = path.relative(GRAMMARS, file);
+    if (relative.startsWith('..') || path.isAbsolute(relative))
+        throw new Error(`Grammar family ${family} has an invalid presentation path`);
+    const doc = parseYaml(fs.readFileSync(file, 'utf8'));
+    const data = doc?.presentation?.[name]; // reason: parsed YAML from disk, validated below
+    if (!data || typeof data !== 'object')
+        throw new Error(`Grammar family ${family} has no ${name} presentation data`);
+    if (Object.hasOwn(data, 'inherits')) {
+        if (Object.keys(data).some((key) => !['inherits', 'ownership', 'contract'].includes(key))) {
+            throw new Error(`Grammar family ${family} mixes inherited and replacement ${name} data`);
+        }
+        return presentationOwner(data.inherits, name, seen);
+    }
+    if (!Array.isArray(data.scale?.steps) || !data.scale.steps.length
+        || !Array.isArray(data.componentOwnership?.rows) || !data.componentOwnership.rows.length
+        || !Array.isArray(data.recipes) || !data.recipes.length) {
+        throw new Error(`Grammar family ${family} has incomplete ${name} presentation data`);
+    }
+    const steps = new Map(data.scale.steps.map((step) => [step.id, step]));
+    if (steps.size !== data.scale.steps.length || data.scale.steps.some((step) => typeof step.id !== 'string'
+        || !step.id || (name === 'padding' && (remPx(step.value) === null || remPx(step.value) < 0)))) {
+        throw new Error(`Grammar family ${family} has duplicate or unusable ${name} scale steps`);
     }
-    return presentationOwner(data.inherits, name, seen);
-  }
-  if (!Array.isArray(data.scale?.steps) || !data.scale.steps.length
-    || !Array.isArray(data.componentOwnership?.rows) || !data.componentOwnership.rows.length
-    || !Array.isArray(data.recipes) || !data.recipes.length) {
-    throw new Error(`Grammar family ${family} has incomplete ${name} presentation data`);
-  }
-  const steps = new Map(data.scale.steps.map(step => [step.id, step]));
-  if (steps.size !== data.scale.steps.length || data.scale.steps.some(step => typeof step.id !== 'string'
-    || !step.id || (name === 'padding' && (remPx(step.value) === null || remPx(step.value) < 0)))) {
-    throw new Error(`Grammar family ${family} has duplicate or unusable ${name} scale steps`);
-  }
-  if (data.componentOwnership.rows.some(row => !steps.has(row.rule))) {
-    throw new Error(`Grammar family ${family} has a component ${name === 'padding' ? 'inset' : 'font rank'} without a scale value`);
-  }
-  if (data.recipes.some(recipe => typeof recipe.title !== 'string' || !recipe.title.trim())) {
-    throw new Error(`Grammar family ${family} has a ${name} recipe without its concrete title`);
-  }
-  if (name === 'font') validateFontGuidance(data);
-  return { data, source: `knowledge/grammars/${relative.split(path.sep).join('/')}#presentation.${name}` };
+    if (data.componentOwnership.rows.some((row) => !steps.has(row.rule))) {
+        throw new Error(`Grammar family ${family} has a component ${name === 'padding' ? 'inset' : 'font rank'} without a scale value`);
+    }
+    if (data.recipes.some((recipe) => typeof recipe.title !== 'string' || !recipe.title.trim())) {
+        throw new Error(`Grammar family ${family} has a ${name} recipe without its concrete title`);
+    }
+    if (name === 'font')
+        validateFontGuidance(data);
+    return { data, source: `knowledge/grammars/${relative.split(path.sep).join('/')}#presentation.${name}` };
 }
-
 /** Preserve every universal case while attaching the exact renderer recipe and its numerical owner. */
 function presentationTopic(topic, owner, name) {
-  const { data, source } = owner;
-  const recipes = new Map(data.recipes.map(recipe => [recipe.rule, recipe]));
-  const rules = topic.doc.rules ?? [];
-  if (recipes.size !== data.recipes.length || recipes.size !== rules.length) {
-    throw new Error(`Grammar ${name} recipes do not cover the universal rule identities exactly once`);
-  }
-  const attached = rules.map(rule => {
-    const recipe = recipes.get(rule.id);
-    const byCase = new Map((recipe?.cases ?? []).map(item => [item.id, item]));
-    if (!recipe || byCase.size !== recipe.cases.length || byCase.size !== (rule.cases ?? []).length) {
-      throw new Error(`Grammar ${name} recipe ${rule.id} does not cover its universal cases exactly once`);
+    const { data, source } = owner;
+    const recipes = new Map(data.recipes.map((recipe) => [recipe.rule, recipe]));
+    const rules = topic.doc.rules ?? [];
+    if (recipes.size !== data.recipes.length || recipes.size !== rules.length) {
+        throw new Error(`Grammar ${name} recipes do not cover the universal rule identities exactly once`);
     }
-    const cases = rule.cases.map(item => {
-      const concrete = byCase.get(item.id);
-      if (!concrete || typeof concrete.render !== 'string' || typeof concrete.owner !== 'string') {
-        throw new Error(`Grammar ${name} recipe ${rule.id}/${item.id} has no renderer contract`);
-      }
-      return { ...item, owner: concrete.owner, render: concrete.render, recipeSource: source };
+    const attached = rules.map((rule) => {
+        const recipe = recipes.get(rule.id);
+        const byCase = new Map((recipe?.cases ?? []).map((item) => [item.id, item]));
+        if (!recipe || byCase.size !== recipe.cases.length || byCase.size !== (rule.cases ?? []).length) {
+            throw new Error(`Grammar ${name} recipe ${rule.id} does not cover its universal cases exactly once`);
+        }
+        const cases = rule.cases.map((item) => {
+            const concrete = byCase.get(item.id);
+            if (!concrete || typeof concrete.render !== 'string' || typeof concrete.owner !== 'string') {
+                throw new Error(`Grammar ${name} recipe ${rule.id}/${item.id} has no renderer contract`);
+            }
+            return { ...item, owner: concrete.owner, render: concrete.render, recipeSource: source };
+        });
+        return { ...rule, familyTitle: recipe.title, cases };
     });
-    return { ...rule, familyTitle: recipe.title, cases };
-  });
-  const guidance = new Map((topic.doc.guidance ?? []).map(item => [item.id, item]));
-  for (const concrete of data.guidance ?? []) {
-    const semantic = guidance.get(concrete.id);
-    guidance.set(concrete.id, semantic ? { ...semantic, familyRequirement: concrete.requirement, familySource: source }
-      : { ...concrete, familySource: source });
-  }
-  return {
-    ...topic,
-    familySource: source,
-    doc: { ...topic.doc, scale: data.scale, componentOwnership: data.componentOwnership,
-      guidance: [...guidance.values()], rules: attached },
-  };
+    const guidance = new Map((topic.doc.guidance ?? []).map((item) => [item.id, item]));
+    for (const concrete of data.guidance ?? []) {
+        const semantic = guidance.get(concrete.id);
+        guidance.set(concrete.id, semantic ? { ...semantic, familyRequirement: concrete.requirement, familySource: source }
+            : { ...concrete, familySource: source });
+    }
+    return {
+        ...topic,
+        familySource: source,
+        doc: { ...topic.doc, scale: data.scale, componentOwnership: data.componentOwnership,
+            guidance: [...guidance.values()], rules: attached },
+    };
 }
-
 /**
  * Bind supported universal presentation cases to the selected family's numerical recipes without mutation.
  * Missing family data and incomplete coverage fail visibly rather than selecting another family.
@@ -139,14 +139,17 @@ function presentationTopic(topic, owner, name) {
  * @returns {{ family: string, knowledge: object[] }} Selected family and proof-ready topics with owner provenance.
  */
 export function familyPresentationKnowledge(knowledge, { family = null, repo = null } = {}) {
-  const selected = selectedFamily(family, repo);
-  const topics = knowledge.filter(topic => topic.rel.endsWith(PADDING_TOPIC));
-  if (topics.length !== 1) throw new Error('Presentation proof needs exactly one universal padding topic');
-  const decorated = new Map();
-  for (const name of TOPIC_NAMES) {
-    const matches = knowledge.filter(topic => topic.rel.endsWith(`presentation/${name}.yaml`));
-    if (matches.length > 1) throw new Error(`Presentation proof has duplicate universal ${name} topics`);
-    if (matches.length) decorated.set(matches[0], presentationTopic(matches[0], presentationOwner(selected, name), name));
-  }
-  return { family: selected, knowledge: knowledge.map(topic => decorated.get(topic) ?? topic) };
+    const selected = selectedFamily(family, repo);
+    const topics = knowledge.filter((topic) => topic.rel.endsWith(PADDING_TOPIC));
+    if (topics.length !== 1)
+        throw new Error('Presentation proof needs exactly one universal padding topic');
+    const decorated = new Map();
+    for (const name of TOPIC_NAMES) {
+        const matches = knowledge.filter((topic) => topic.rel.endsWith(`presentation/${name}.yaml`));
+        if (matches.length > 1)
+            throw new Error(`Presentation proof has duplicate universal ${name} topics`);
+        if (matches.length)
+            decorated.set(matches[0], presentationTopic(matches[0], presentationOwner(selected, name), name));
+    }
+    return { family: selected, knowledge: knowledge.map((topic) => decorated.get(topic) ?? topic) };
 }

package/runtime/scripts/hfs/linear-text.d.mts

@@ -0,0 +1,6 @@
+/** `text` without its trailing characters that are in `chars`. */
+export declare function trimTrailingChars(text: string, chars: string): string;
+/** `text` with every `<name>` placeholder (a `<`, one or more characters other than `>`, a `>`) replaced by `replacement`. */
+export declare function replacePlaceholders(text: string, replacement: string): string;
+/** Whether `text` holds a `<name>` placeholder. */
+export declare const hasPlaceholder: (text: string) => boolean;

package/runtime/scripts/hfs/linear-text.mjs

@@ -1,30 +1,30 @@
 // Linear-time text trimming and `<placeholder>` replacement for the HFS path and prose checks.
-
 /** `text` without its trailing characters that are in `chars`. */
 export function trimTrailingChars(text, chars) {
-  let last = text.length - 1;
-  while (last >= 0 && chars.includes(text[last])) last -= 1;
-  return text.slice(0, last + 1);
+    let last = text.length - 1;
+    while (last >= 0 && chars.includes(text[last]))
+        last -= 1;
+    return text.slice(0, last + 1);
 }
-
 /** `text` with every `<name>` placeholder (a `<`, one or more characters other than `>`, a `>`) replaced by `replacement`. */
 export function replacePlaceholders(text, replacement) {
-  let out = '';
-  let from = 0;
-  let open = text.indexOf('<');
-  while (open >= 0) {
-    const close = text.indexOf('>', open + 1);
-    if (close < 0) break;
-    if (close === open + 1) {
-      open = text.indexOf('<', close);
-    } else {
-      out += text.slice(from, open) + replacement;
-      from = close + 1;
-      open = text.indexOf('<', from);
+    let out = '';
+    let from = 0;
+    let open = text.indexOf('<');
+    while (open >= 0) {
+        const close = text.indexOf('>', open + 1);
+        if (close < 0)
+            break;
+        if (close === open + 1) {
+            open = text.indexOf('<', close);
+        }
+        else {
+            out += text.slice(from, open) + replacement;
+            from = close + 1;
+            open = text.indexOf('<', from);
+        }
     }
-  }
-  return out + text.slice(from);
+    return out + text.slice(from);
 }
-
 /** Whether `text` holds a `<name>` placeholder. */
 export const hasPlaceholder = (text) => replacePlaceholders(text, '') !== text;