@starci/hfs 4.11.22 → 4.12.2

package/sync/managed.d.mts

@@ -0,0 +1,23 @@
+import type { Presets, SlotManifest } from './index.mjs';
+type ParseYaml = (text: string) => any;
+/** One finding of the managed-file check: a code, a level, the path it is about and its message, with the extras some codes carry. */
+export interface ManagedFinding {
+    code: string;
+    level: string;
+    path: string;
+    message: string;
+    [extra: string]: unknown;
+}
+/**
+ * The managed-file findings of the repository at `repoRoot` whose tracked paths are `tracked`. A repository whose hfs.json
+ * is unreadable has none: the slot check reports the declaration. A missing preset or an unreadable stack declaration is
+ * a SyncError the caller reports as a refusal.
+ */
+export declare function managedFindings({ repoRoot, tracked, presets, parseYaml, manifest }: {
+    repoRoot: string;
+    tracked: readonly string[];
+    presets?: Presets | undefined;
+    parseYaml?: ParseYaml | undefined;
+    manifest?: SlotManifest | undefined;
+}): Promise<ManagedFinding[]>;
+export {};

package/sync/managed.mjs

@@ -35,14 +35,13 @@ import { SyncError, checkTargets, renderRepo } from './index.mjs';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
 import { readDeclaredSonarGate, sonarGateName } from './sonar-key.mjs';
 import { TS_STRICT_FILE, tsStrictFindings } from './ts-strict.mjs';
-
 // The managed one-liners whose difference from the render is the proof that no rule is off, warned or redefined (R17).
 const ONE_LINER_FILES = new Set(['eslint.config.mjs', 'stylelint.config.mjs']);
 const SONAR_PROPERTIES_FILE = 'sonar-project.properties';
 // The files whose whole content is a statement of the coverage scope, and the one line of the Sonar file that is (R204).
 const COVERAGE_SCOPE_FILES = new Set(['be/jest.config.js', 'codecov.yml']);
 const SONAR_COVERAGE_LINE = 'sonar.coverage.exclusions=';
-const statesCoverageScope = result => COVERAGE_SCOPE_FILES.has(result.path) || (result.path === SONAR_PROPERTIES_FILE && String(result.difference?.expected ?? '').startsWith(SONAR_COVERAGE_LINE));
+const statesCoverageScope = (result) => COVERAGE_SCOPE_FILES.has(result.path) || (result.path === SONAR_PROPERTIES_FILE && String(result.difference?.expected ?? '').startsWith(SONAR_COVERAGE_LINE));
 const SONAR_GATE_FILE = new URL('../runtime/knowledge/sonar-gate.yaml', import.meta.url);
 const MAX_SCANNED_BYTES = 1024 * 1024;
 const RULE_FILE = /\.[cm]?[jt]s$/;
@@ -59,122 +58,133 @@ const STYLELINT_IMPORT = /["']stylelint["']/;
 const TOOL_CONFIG_KEYS = ['eslintConfig', 'stylelint', 'prettier', 'lint-staged', 'jest'];
 // Flags that swap the configuration or switch a rule or a directive off. Only a line that runs the tool is judged.
 const TOOL_FLAGS = [
-  { tool: /\beslint\b/, flag: /(?<![\w-])(--rule|--no-inline-config|--no-eslintrc|--no-config-lookup|--config|-c|--ignore-pattern|--ignore-path|--no-ignore|--rulesdir|--plugin|--parser|--parser-options|--env|--global)(?![\w-])/ },
-  { tool: /\bstylelint\b/, flag: /(?<![\w-])(--config|--config-basedir|--ignore-path|--ignore-pattern|--custom-syntax|--disable-default-ignores)(?![\w-])/ },
-  { tool: /\bprettier\b/, flag: /(?<![\w-])(--config|--no-config|--ignore-path|--no-editorconfig|--plugin)(?![\w-])/ },
+    { tool: /\beslint\b/, flag: /(?<![\w-])(--rule|--no-inline-config|--no-eslintrc|--no-config-lookup|--config|-c|--ignore-pattern|--ignore-path|--no-ignore|--rulesdir|--plugin|--parser|--parser-options|--env|--global)(?![\w-])/ },
+    { tool: /\bstylelint\b/, flag: /(?<![\w-])(--config|--config-basedir|--ignore-path|--ignore-pattern|--custom-syntax|--disable-default-ignores)(?![\w-])/ },
+    { tool: /\bprettier\b/, flag: /(?<![\w-])(--config|--no-config|--ignore-path|--no-editorconfig|--plugin)(?![\w-])/ },
 ];
-
 const readText = (root, file) => {
-  try {
-    const target = path.join(root, file);
-    return fs.statSync(target).size > MAX_SCANNED_BYTES ? null : fs.readFileSync(target, 'utf8');
-  } catch {
-    return null;
-  }
+    try {
+        const target = path.join(root, file);
+        return fs.statSync(target).size > MAX_SCANNED_BYTES ? null : fs.readFileSync(target, 'utf8');
+    }
+    catch {
+        return null;
+    }
 };
-
 const local = (file, message) => ({ code: 'HFS_TOOL_CONFIG_LOCAL', level: 'error', path: file, message });
-
 /** Every managed target that exists on disk but differs from its render, as one finding each. */
 function driftFindings(repoRoot, targets) {
-  const findings = [];
-  for (const result of checkTargets(repoRoot, targets)) {
-    const target = targets.find(candidate => candidate.path === result.path);
-    if (!fs.existsSync(path.join(repoRoot, result.path)) || result.status === 'ok') continue;
-    // A side's tsconfig.json (be/tsconfig.json, fe/tsconfig.json: the side's own root) is judged by flag (R22).
-    if (target.scope !== 'app' && result.path === `${target.scope}/${TS_STRICT_FILE}`) {
-      const flags = tsStrictFindings(fs.readFileSync(path.join(repoRoot, result.path), 'utf8'), target.content, result.path);
-      if (flags.length) {
-        findings.push(...flags);
-        continue;
-      }
+    const findings = [];
+    for (const result of checkTargets(repoRoot, targets)) {
+        const target = targets.find(candidate => candidate.path === result.path);
+        if (!fs.existsSync(path.join(repoRoot, result.path)) || result.status === 'ok')
+            continue;
+        // A side's tsconfig.json (be/tsconfig.json, fe/tsconfig.json: the side's own root) is judged by flag (R22).
+        if (target.scope !== 'app' && result.path === `${target.scope}/${TS_STRICT_FILE}`) {
+            const flags = tsStrictFindings(fs.readFileSync(path.join(repoRoot, result.path), 'utf8'), target.content, result.path);
+            if (flags.length) {
+                findings.push(...flags);
+                continue;
+            }
+        }
+        const code = target.mode === 'block' ? 'HFS_GITIGNORE_BLOCK_DRIFT' : ONE_LINER_FILES.has(path.posix.basename(result.path)) ? 'HFS_RULE_OFF_WITHOUT_REPLACEMENT' : statesCoverageScope(result) ? 'HFS_COVERAGE_SCOPE_DRIFT' : result.path === SONAR_PROPERTIES_FILE ? 'HFS_SONAR_CONFIG' : 'HFS_MANAGED_FILE_DRIFT';
+        const where = result.difference ? `; line ${result.difference.line} expected ${JSON.stringify(result.difference.expected)}, found ${JSON.stringify(result.difference.actual)}` : '';
+        const what = target.mode === 'block' ? `the managed block of ${result.path} is ${result.status === 'missing' ? 'missing' : 'not its render'}` : target.mode === 'scripts' ? 'the scripts block of package.json is not the rendered one' : `${result.path} is not its render${code === 'HFS_RULE_OFF_WITHOUT_REPLACEMENT' ? ', so a rule can be off or redefined in it' : code === 'HFS_COVERAGE_SCOPE_DRIFT' ? ', so it no longer states the coverage scope derived from the slot manifest' : ''}`;
+        findings.push({ code, level: 'error', path: result.path, mode: target.mode, expectedHash: result.expectedHash, ...(result.actualHash ? { actualHash: result.actualHash } : {}), message: `${what} (expected sha256 ${result.expectedHash.slice(0, 12)}${result.actualHash ? `, found ${result.actualHash.slice(0, 12)}` : ''}${where}); run "npx --no-install starci app sync --execute"` });
     }
-    const code = target.mode === 'block' ? 'HFS_GITIGNORE_BLOCK_DRIFT' : ONE_LINER_FILES.has(path.posix.basename(result.path)) ? 'HFS_RULE_OFF_WITHOUT_REPLACEMENT' : statesCoverageScope(result) ? 'HFS_COVERAGE_SCOPE_DRIFT' : result.path === SONAR_PROPERTIES_FILE ? 'HFS_SONAR_CONFIG' : 'HFS_MANAGED_FILE_DRIFT';
-    const where = result.difference ? `; line ${result.difference.line} expected ${JSON.stringify(result.difference.expected)}, found ${JSON.stringify(result.difference.actual)}` : '';
-    const what = target.mode === 'block' ? `the managed block of ${result.path} is ${result.status === 'missing' ? 'missing' : 'not its render'}` : target.mode === 'scripts' ? 'the scripts block of package.json is not the rendered one' : `${result.path} is not its render${code === 'HFS_RULE_OFF_WITHOUT_REPLACEMENT' ? ', so a rule can be off or redefined in it' : code === 'HFS_COVERAGE_SCOPE_DRIFT' ? ', so it no longer states the coverage scope derived from the slot manifest' : ''}`;
-    findings.push({ code, level: 'error', path: result.path, mode: target.mode, expectedHash: result.expectedHash, ...(result.actualHash ? { actualHash: result.actualHash } : {}), message: `${what} (expected sha256 ${result.expectedHash.slice(0, 12)}${result.actualHash ? `, found ${result.actualHash.slice(0, 12)}` : ''}${where}); run "npx starci app sync --write"` });
-  }
-  return findings;
+    return findings;
 }
-
 /** R11: the quality gate the be side's stack declaration names is the one gate of the bundled knowledge/sonar-gate.yaml. */
 function sonarGateFindings(repoRoot, parseYaml, edition) {
-  const declared = readDeclaredSonarGate(repoRoot, { parseYaml });
-  if (declared === null) return [];
-  const gate = sonarGateName((parseYaml ?? bundledParseYaml)(fs.readFileSync(SONAR_GATE_FILE, 'utf8')), edition);
-  if (declared.qualityGate === gate) return [];
-  return [{ code: 'HFS_SONAR_CONFIG', level: 'error', path: declared.file, message: `${declared.file} services.sonar.qualityGate is ${declared.qualityGate ?? 'absent'}; every product names the one gate ${gate} of knowledge/sonar-gate.yaml and states no threshold of its own` }];
+    const declared = readDeclaredSonarGate(repoRoot, { parseYaml });
+    if (declared === null)
+        return [];
+    const gate = sonarGateName((parseYaml ?? bundledParseYaml)(fs.readFileSync(SONAR_GATE_FILE, 'utf8')), edition);
+    if (declared.qualityGate === gate)
+        return [];
+    return [{ code: 'HFS_SONAR_CONFIG', level: 'error', path: declared.file, message: `${declared.file} services.sonar.qualityGate is ${declared.qualityGate ?? 'absent'}; every product names the one gate ${gate} of knowledge/sonar-gate.yaml and states no threshold of its own` }];
 }
-
 function ruleFileFindings(repoRoot, tracked) {
-  const findings = [];
-  for (const file of tracked.filter(candidate => RULE_FILE.test(candidate))) {
-    const text = readText(repoRoot, file);
-    if (text === null) continue;
-    if (RULE_META.test(text) && RULE_CREATE.test(text)) findings.push(local(file, `${file} defines an ESLint rule; a repository defines no rule, the canon plugin is the only source`));
-    else if (STYLELINT_CREATE_PLUGIN.test(text) && STYLELINT_IMPORT.test(text)) findings.push(local(file, `${file} defines a stylelint plugin; a repository defines no rule, @starci/stylelint-canon is the only source`));
-  }
-  return findings;
+    const findings = [];
+    for (const file of tracked.filter(candidate => RULE_FILE.test(candidate))) {
+        const text = readText(repoRoot, file);
+        if (text === null)
+            continue;
+        if (RULE_META.test(text) && RULE_CREATE.test(text))
+            findings.push(local(file, `${file} defines an ESLint rule; a repository defines no rule, the canon plugin is the only source`));
+        else if (STYLELINT_CREATE_PLUGIN.test(text) && STYLELINT_IMPORT.test(text))
+            findings.push(local(file, `${file} defines a stylelint plugin; a repository defines no rule, @starci/stylelint-canon is the only source`));
+    }
+    return findings;
 }
-
 /** A package.json that keeps a tool's configuration under a key: a second source beside the managed file. */
 function toolKeyFindings(repoRoot, tracked) {
-  const findings = [];
-  for (const file of tracked.filter(candidate => candidate === 'package.json' || candidate.endsWith('/package.json'))) {
-    const text = readText(repoRoot, file);
-    if (text === null) continue;
-    let manifest;
-    try { manifest = JSON.parse(text); } catch { continue; }
-    for (const key of TOOL_CONFIG_KEYS) {
-      if (manifest && typeof manifest === 'object' && Object.hasOwn(manifest, key)) findings.push(local(file, `${file} carries a "${key}" configuration; the tool's configuration is the managed file and nothing else`));
+    const findings = [];
+    for (const file of tracked.filter(candidate => candidate === 'package.json' || candidate.endsWith('/package.json'))) {
+        const text = readText(repoRoot, file);
+        if (text === null)
+            continue;
+        let manifest;
+        try {
+            manifest = JSON.parse(text);
+        }
+        catch {
+            continue;
+        }
+        for (const key of TOOL_CONFIG_KEYS) {
+            if (manifest && typeof manifest === 'object' && Object.hasOwn(manifest, key))
+                findings.push(local(file, `${file} carries a "${key}" configuration; the tool's configuration is the managed file and nothing else`));
+        }
     }
-  }
-  return findings;
+    return findings;
 }
-
 function flagFindings(repoRoot, tracked, managed) {
-  const findings = [];
-  const commandLines = (file, text) => {
-    if (file.endsWith('package.json')) {
-      try {
-        return Object.entries(JSON.parse(text).scripts ?? {}).map(([name, command]) => [`script ${name}`, String(command)]);
-      } catch {
-        return [];
-      }
-    }
-    return text.split('\n').map((line, index) => [`line ${index + 1}`, line]);
-  };
-  for (const file of tracked.filter(candidate => !managed.has(candidate) && (SCRIPT_FILE.test(candidate) || candidate.endsWith('/package.json')))) {
-    const text = readText(repoRoot, file);
-    if (text === null) continue;
-    for (const [where, line] of commandLines(file, text)) {
-      for (const { tool, flag } of TOOL_FLAGS) {
-        const hit = tool.test(line) && flag.exec(line);
-        if (hit) findings.push(local(file, `${file} (${where}) runs ${tool.source.replace(/\\b/g, '')} with ${hit[1]}, which swaps or switches off the canon configuration; run the tool with no such flag`));
-      }
+    const findings = [];
+    const commandLines = (file, text) => {
+        if (file.endsWith('package.json')) {
+            try {
+                return Object.entries(JSON.parse(text).scripts ?? {}).map(([name, command]) => [`script ${name}`, String(command)]);
+            }
+            catch {
+                return [];
+            }
+        }
+        return text.split('\n').map((line, index) => [`line ${index + 1}`, line]);
+    };
+    for (const file of tracked.filter(candidate => !managed.has(candidate) && (SCRIPT_FILE.test(candidate) || candidate.endsWith('/package.json')))) {
+        const text = readText(repoRoot, file);
+        if (text === null)
+            continue;
+        for (const [where, line] of commandLines(file, text)) {
+            for (const { tool, flag } of TOOL_FLAGS) {
+                const hit = tool.test(line) && flag.exec(line);
+                if (hit)
+                    findings.push(local(file, `${file} (${where}) runs ${tool.source.replace(/\\b/g, '')} with ${hit[1]}, which swaps or switches off the canon configuration; run the tool with no such flag`));
+            }
+        }
     }
-  }
-  return findings;
+    return findings;
 }
-
 /**
  * The managed-file findings of the repository at `repoRoot` whose tracked paths are `tracked`. A repository whose hfs.json
  * is unreadable has none: the slot check reports the declaration. A missing preset or an unreadable stack declaration is
  * a SyncError the caller reports as a refusal.
  */
 export async function managedFindings({ repoRoot, tracked, presets, parseYaml, manifest }) {
-  let rendered;
-  try {
-    rendered = await renderRepo(repoRoot, { presets, parseYaml, ...(manifest ? { manifest } : {}) });
-  } catch (error) {
-    if (error instanceof SyncError && error.code === 'HFS_SYNC_HFS_INVALID') return [];
-    throw error;
-  }
-  const { targets } = rendered;
-  const findings = driftFindings(repoRoot, targets);
-  findings.push(...sonarGateFindings(repoRoot, parseYaml, rendered.hfs.edition ?? 'full'));
-  findings.push(...ruleFileFindings(repoRoot, tracked));
-  findings.push(...toolKeyFindings(repoRoot, tracked));
-  findings.push(...flagFindings(repoRoot, tracked, new Set(targets.map(target => target.path))));
-  return findings;
+    let rendered;
+    try {
+        rendered = await renderRepo(repoRoot, { presets, parseYaml, ...(manifest ? { manifest } : {}) });
+    }
+    catch (error) {
+        if (error instanceof SyncError && error.code === 'HFS_SYNC_HFS_INVALID')
+            return [];
+        throw error;
+    }
+    const { targets } = rendered;
+    const findings = driftFindings(repoRoot, targets);
+    findings.push(...sonarGateFindings(repoRoot, parseYaml, rendered.hfs.edition ?? 'full'));
+    findings.push(...ruleFileFindings(repoRoot, tracked));
+    findings.push(...toolKeyFindings(repoRoot, tracked));
+    findings.push(...flagFindings(repoRoot, tracked, new Set(targets.map(target => target.path))));
+    return findings;
 }

package/sync/quality-services.d.mts

@@ -0,0 +1,35 @@
+type ParseYaml = (text: string) => any;
+/** Apps without any service block retain the legacy CI defaults until they declare their services. */
+export declare function hasDeclaredServices(root: string, { parseYaml }?: {
+    parseYaml?: ParseYaml | undefined;
+}): boolean;
+/** Missing or unreadable manifests preserve the shared quality defaults; example apps use the runtime example policy. */
+export declare function readDeclaredQuality(root: string, { parseYaml }?: {
+    parseYaml?: ParseYaml | undefined;
+}): any;
+/** SonarCloud names its organization and public host; SonarQube uses the manifest host. */
+export declare function sonarHostLine(sonar: {
+    provider?: string;
+    organization?: string;
+    host?: string;
+} | null | undefined): string;
+/** Dependabot groups minor and patch updates while majors remain per package; security updates have their own immediate group. */
+export declare function dependabotUpdates(dependabot: {
+    ecosystems: string[];
+    schedule: {
+        interval: string;
+        day?: string;
+        time?: string;
+    };
+    groups: {
+        minorPatch: string;
+    };
+    security: string;
+    ignore: string[];
+}): string;
+/** README badges use only public manifest fields and the package repository fallback. */
+export declare function readDeclaredBadges(root: string, { parseYaml, notices }?: {
+    parseYaml?: ParseYaml | undefined;
+    notices?: string[] | undefined;
+}): string;
+export {};

package/sync/quality-services.mjs

@@ -5,59 +5,66 @@ import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
 import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
 import { badgeTokenNotices, renderReadmeBadges } from './readme-badges.mjs';
 import { DECLARATION } from './sonar-key.mjs';
-
 /** Apps without any service block retain the legacy CI defaults until they declare their services. */
 export function hasDeclaredServices(root, { parseYaml = bundledParseYaml } = {}) {
-  try {
-    const doc = parseYaml(fs.readFileSync(path.join(root, DECLARATION), 'utf8'));
-    return Object.keys(doc?.services ?? {}).length > 0;
-  } catch {
-    return false;
-  }
+    try {
+        const doc = parseYaml(fs.readFileSync(path.join(root, DECLARATION), 'utf8'));
+        return Object.keys(doc?.services ?? {}).length > 0;
+    }
+    catch {
+        return false;
+    }
 }
-
 /** Missing or unreadable manifests preserve the shared quality defaults; example apps use the runtime example policy. */
 export function readDeclaredQuality(root, { parseYaml = bundledParseYaml } = {}) {
-  try {
-    const doc = parseYaml(fs.readFileSync(path.join(root, DECLARATION), 'utf8'));
-    return qualityServices(doc, { example: isRuntimeExampleApp(root) });
-  } catch {
-    return qualityServices({});
-  }
+    try {
+        const doc = parseYaml(fs.readFileSync(path.join(root, DECLARATION), 'utf8'));
+        return qualityServices(doc, { example: isRuntimeExampleApp(root) });
+    }
+    catch {
+        return qualityServices({});
+    }
 }
-
 /** SonarCloud names its organization and public host; SonarQube uses the manifest host. */
 export function sonarHostLine(sonar) {
-  if (!sonar) return '';
-  if (sonar.provider === 'sonarcloud') return [sonar.organization ? `sonar.organization=${sonar.organization}` : '', 'sonar.host.url=https://sonarcloud.io'].filter(Boolean).join('\n');
-  return sonar.host ? `sonar.host.url=${sonar.host}` : '';
+    if (!sonar)
+        return '';
+    if (sonar.provider === 'sonarcloud')
+        return [sonar.organization ? `sonar.organization=${sonar.organization}` : '', 'sonar.host.url=https://sonarcloud.io'].filter(Boolean).join('\n');
+    return sonar.host ? `sonar.host.url=${sonar.host}` : '';
 }
-
 /** Dependabot groups minor and patch updates while majors remain per package; security updates have their own immediate group. */
 export function dependabotUpdates(dependabot) {
-  if (!dependabot.ecosystems.length) return ' []';
-  return '\n' + dependabot.ecosystems.map(ecosystem => [
-    `  - package-ecosystem: ${ecosystem}`,
-    ...(ecosystem === 'docker' ? ['    directories:', '      - /be/apps/*', '      - /fe/apps/*'] : ['    directory: /']),
-    '    schedule:',
-    `      interval: ${dependabot.schedule.interval}`,
-    ...(dependabot.schedule.day ? [`      day: ${dependabot.schedule.day}`] : []),
-    ...(dependabot.schedule.time ? [`      time: ${JSON.stringify(dependabot.schedule.time)}`] : []),
-    '    groups:',
-    ...(ecosystem === 'github-actions' ? ['      actions:', '        patterns: ["*"]'] : [
-      ...(dependabot.groups.minorPatch === 'grouped' ? ['      minor-and-patch:', '        update-types: [minor, patch]'] : []),
-      ...(dependabot.security === 'immediate' ? ['      security:', '        applies-to: security-updates', '        patterns: ["*"]', '        update-types: [minor, patch]'] : []),
-    ]),
-    ...(ecosystem === 'npm' && dependabot.ignore.length ? ['    ignore:', ...dependabot.ignore.map(name => `      - dependency-name: ${JSON.stringify(name)}`)] : []),
-  ].join('\n')).join('\n');
+    if (!dependabot.ecosystems.length)
+        return ' []';
+    return '\n' + dependabot.ecosystems.map((ecosystem) => [
+        `  - package-ecosystem: ${ecosystem}`,
+        ...(ecosystem === 'docker' ? ['    directories:', '      - /be/apps/*', '      - /fe/apps/*'] : ['    directory: /']),
+        '    schedule:',
+        `      interval: ${dependabot.schedule.interval}`,
+        ...(dependabot.schedule.day ? [`      day: ${dependabot.schedule.day}`] : []),
+        ...(dependabot.schedule.time ? [`      time: ${JSON.stringify(dependabot.schedule.time)}`] : []),
+        '    groups:',
+        ...(ecosystem === 'github-actions' ? ['      actions:', '        patterns: ["*"]'] : [
+            ...(dependabot.groups.minorPatch === 'grouped' ? ['      minor-and-patch:', '        update-types: [minor, patch]'] : []),
+            ...(dependabot.security === 'immediate' ? ['      security:', '        applies-to: security-updates', '        patterns: ["*"]', '        update-types: [minor, patch]'] : []),
+        ]),
+        ...(ecosystem === 'npm' && dependabot.ignore.length ? ['    ignore:', ...dependabot.ignore.map((name) => `      - dependency-name: ${JSON.stringify(name)}`)] : []),
+    ].join('\n')).join('\n');
 }
-
 /** README badges use only public manifest fields and the package repository fallback. */
 export function readDeclaredBadges(root, { parseYaml = bundledParseYaml, notices } = {}) {
-  let doc = {}, pkg = {};
-  try { doc = parseYaml(fs.readFileSync(path.join(root, DECLARATION), 'utf8')); } catch { /* No declaration. */ }
-  try { pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch { /* No repository fallback. */ }
-  const options = { repository: pkg.repository, example: isRuntimeExampleApp(root) };
-  notices?.push(...badgeTokenNotices(doc, options));
-  return renderReadmeBadges(doc, options);
+    // reason: the declaration and package.json are parsed from disk
+    let doc = {}, pkg = {};
+    try {
+        doc = parseYaml(fs.readFileSync(path.join(root, DECLARATION), 'utf8'));
+    }
+    catch { /* No declaration. */ }
+    try {
+        pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    }
+    catch { /* No repository fallback. */ }
+    const options = { repository: pkg.repository, example: isRuntimeExampleApp(root) };
+    notices?.push(...badgeTokenNotices(doc, options));
+    return renderReadmeBadges(doc, options);
 }

package/sync/readme-badges.d.mts

@@ -0,0 +1,13 @@
+type Declaration = any;
+/** The options the badge renderers read: the package repository fallback and whether the app is a runtime example. */
+interface BadgeOptions {
+    repository?: string | {
+        url?: string;
+    } | undefined;
+    example?: boolean;
+}
+/** Render live CI, coverage, quality gate and Dependabot badges only when a GitHub repository is declared or inferable; no network is used. */
+export declare function renderReadmeBadges(doc: Declaration, { repository, example }?: BadgeOptions): string;
+/** Private repositories need public-safe badge tokens only for badges the renderer actually emits; examples never receive notices. */
+export declare function badgeTokenNotices(doc: Declaration, { example, repository }?: BadgeOptions): string[];
+export {};

package/sync/readme-badges.mjs

@@ -1,60 +1,61 @@
 import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
-
 /** Package repository fallbacks must name a GitHub HTTPS or Git transport URL. */
 function githubRepository(repository) {
-  const url = typeof repository === 'string' ? repository : repository?.url;
-  const match = /^(?:git\+)?https:\/\/github\.com\/([^/]+\/[^/#?]+)|^git@github\.com:([^/]+\/[^/#?]+)/.exec(url ?? '');
-  return (match?.[1] ?? match?.[2] ?? '').replace(/\.git$/, '');
+    const url = typeof repository === 'string' ? repository : repository?.url;
+    const match = /^(?:git\+)?https:\/\/github\.com\/([^/]+\/[^/#?]+)|^git@github\.com:([^/]+\/[^/#?]+)/.exec(url ?? '');
+    return (match?.[1] ?? match?.[2] ?? '').replace(/\.git$/, '');
 }
-
 /** Notice code (never an error) of a private repository badge rendered without its read-only badge token. */
 const BADGE_TOKEN_NOTICE = 'README_BADGE_TOKEN_MISSING';
-
 const badge = (name, image, link) => `[![${name}](${image})](${link})`;
-
 /** Render live CI, coverage, quality gate and Dependabot badges only when a GitHub repository is declared or inferable; no network is used. */
 export function renderReadmeBadges(doc, { repository, example = false } = {}) {
-  const github = doc?.ci?.github ?? {};
-  const repo = github.repository ?? githubRepository(repository);
-  if (!repo) return '';
-  const branch = encodeURIComponent(github.defaultBranch ?? 'main');
-  const workflow = encodeURIComponent(github.workflow ?? 'ci.yml');
-  const base = `https://github.com/${repo}`;
-  const quality = qualityServices(doc, { example });
-  const lines = [badge('CI', `${base}/actions/workflows/${workflow}/badge.svg?branch=${branch}`, `${base}/actions/workflows/${workflow}`)];
-  if (quality.codecov.enabled) {
-    const params = [];
-    if (quality.codecov.flag) params.push(`flag=${encodeURIComponent(quality.codecov.flag)}`);
-    if (doc?.services?.codecov?.badgeToken) params.push(`token=${encodeURIComponent(doc.services.codecov.badgeToken)}`);
-    const flag = params.length ? `?${params.join('&')}` : '';
-    lines.push(badge('Codecov', `https://codecov.io/gh/${repo}/branch/${branch}/graph/badge.svg${flag}`, `https://codecov.io/gh/${repo}`));
-  }
-  const sonar = sonarBadge(doc, quality.sonar, example);
-  if (sonar) lines.push(sonar);
-  if (quality.dependabot.ecosystems.length) {
-    const updates = `${base}/actions/workflows/dependabot/dependabot-updates`;
-    lines.push(badge('Dependabot', `${updates}/badge.svg`, updates));
-  }
-  return lines.join('\n');
+    const github = doc?.ci?.github ?? {};
+    const repo = github.repository ?? githubRepository(repository);
+    if (!repo)
+        return '';
+    const branch = encodeURIComponent(github.defaultBranch ?? 'main');
+    const workflow = encodeURIComponent(github.workflow ?? 'ci.yml');
+    const base = `https://github.com/${repo}`;
+    const quality = qualityServices(doc, { example });
+    const lines = [badge('CI', `${base}/actions/workflows/${workflow}/badge.svg?branch=${branch}`, `${base}/actions/workflows/${workflow}`)];
+    if (quality.codecov.enabled) {
+        const params = [];
+        if (quality.codecov.flag)
+            params.push(`flag=${encodeURIComponent(quality.codecov.flag)}`);
+        if (doc?.services?.codecov?.badgeToken)
+            params.push(`token=${encodeURIComponent(doc.services.codecov.badgeToken)}`);
+        const flag = params.length ? `?${params.join('&')}` : '';
+        lines.push(badge('Codecov', `https://codecov.io/gh/${repo}/branch/${branch}/graph/badge.svg${flag}`, `https://codecov.io/gh/${repo}`));
+    }
+    const sonar = sonarBadge(doc, quality.sonar, example);
+    if (sonar)
+        lines.push(sonar);
+    if (quality.dependabot.ecosystems.length) {
+        const updates = `${base}/actions/workflows/dependabot/dependabot-updates`;
+        lines.push(badge('Dependabot', `${updates}/badge.svg`, updates));
+    }
+    return lines.join('\n');
 }
-
 /** Runtime examples use the organization-qualified key passed by examples.yml; products declare their complete project key. */
 function sonarBadge(doc, sonar, example) {
-  if (!sonar?.projectKey) return '';
-  const host = sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : sonar.host?.replace(/\/$/, '');
-  if (!host) return '';
-  const organization = sonar.organization ?? doc?.ci?.vars?.find(entry => entry.name === sonar.organizationVar)?.value;
-  const prefix = example && organization ? `${organization}_` : '';
-  const key = encodeURIComponent(prefix + sonar.projectKey);
-  const token = doc?.services?.sonar?.badgeToken ? `&token=${encodeURIComponent(doc.services.sonar.badgeToken)}` : '';
-  return badge('Quality Gate', `${host}/api/project_badges/measure?project=${key}&metric=alert_status${token}`, `${host}/dashboard?id=${key}`);
+    if (!sonar?.projectKey)
+        return '';
+    const host = sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : sonar.host?.replace(/\/$/, '');
+    if (!host)
+        return '';
+    const organization = sonar.organization ?? doc?.ci?.vars?.find((entry) => entry.name === sonar.organizationVar)?.value;
+    const prefix = example && organization ? `${organization}_` : '';
+    const key = encodeURIComponent(prefix + sonar.projectKey);
+    const token = doc?.services?.sonar?.badgeToken ? `&token=${encodeURIComponent(doc.services.sonar.badgeToken)}` : '';
+    return badge('Quality Gate', `${host}/api/project_badges/measure?project=${key}&metric=alert_status${token}`, `${host}/dashboard?id=${key}`);
 }
-
 /** Private repositories need public-safe badge tokens only for badges the renderer actually emits; examples never receive notices. */
 export function badgeTokenNotices(doc, { example = false, repository } = {}) {
-  if (example || doc?.ci?.github?.visibility !== 'private') return [];
-  const rendered = renderReadmeBadges(doc, { example, repository });
-  return [['codecov', 'Codecov', 'Codecov'], ['sonar', 'Sonar', 'Quality Gate']]
-    .filter(([id, , label]) => !doc?.services?.[id]?.badgeToken && rendered.includes(`[![${label}](`))
-    .map(([id, name]) => `${BADGE_TOKEN_NOTICE} notice: the ${name} badge of a private repository renders "unknown" without services.${id}.badgeToken (a read-only badge token, not a CI secret)`);
+    if (example || doc?.ci?.github?.visibility !== 'private')
+        return [];
+    const rendered = renderReadmeBadges(doc, { example, repository });
+    return [['codecov', 'Codecov', 'Codecov'], ['sonar', 'Sonar', 'Quality Gate']]
+        .filter(([id, , label]) => !doc?.services?.[id]?.badgeToken && rendered.includes(`[![${label}](`))
+        .map(([id, name]) => `${BADGE_TOKEN_NOTICE} notice: the ${name} badge of a private repository renders "unknown" without services.${id}.badgeToken (a read-only badge token, not a CI secret)`);
 }

package/sync/sonar-key.d.mts

@@ -0,0 +1,31 @@
+type Declaration = any;
+type ParseYaml = (text: string) => Declaration;
+/** The stack declaration, app-relative: .starcistacks sits at the app root, beside be/, fe/ and .starciwork. */
+export declare const DECLARATION: string;
+/** The repository name the declaration lists its projects under: the app package.json name, else the folder name. */
+export declare function repositoryName(root: string): string;
+/** The keys services.sonar declares for `repository` in a parsed declaration (empty when it declares none). */
+export declare function declaredSonarKeys(declaration: Declaration, repository: string): string[];
+/**
+ * The declared key of the app at `root`, or null when the app has no stack declaration or the declaration names none for it.
+ * Two keys for one app are refused through `fail`. `parseYaml(text)` is injected; the default is the YAML parser bundled in this
+ * package (the package installs with no node_modules).
+ */
+export declare function readDeclaredSonarKey(root: string, { parseYaml, fail }: {
+    parseYaml?: ParseYaml | undefined;
+    fail: (message: string) => unknown;
+}): Promise<string | null>;
+/**
+ * The quality gate the declaration names for Sonar: `{ file, qualityGate }` (file app-relative), or null when there is no
+ * declaration, Sonar is disabled in it, or it declares no Sonar service. The one gate is knowledge/sonar-gate.yaml; an app names it
+ * and never states thresholds of its own.
+ */
+export declare function readDeclaredSonarGate(root: string, { parseYaml }?: {
+    parseYaml?: ParseYaml | undefined;
+}): {
+    file: string;
+    qualityGate: string | null;
+} | null;
+/** The quality-gate name for an app edition from the one sonar-gate document. */
+export declare function sonarGateName(document: Declaration, edition?: string): string | null;
+export {};