@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/hfs/rules/contract.d.mts

@@ -0,0 +1,26 @@
+import type { Finding, Parsed, Repo, Resolver } from './rule-types.mjs';
+/** The findings of R23 for the be side at `repoRoot` (a side of another profile has none). */
+export declare function contractFindings({ repoRoot, files, repo, resolver }: {
+    repoRoot: string;
+    files: string[];
+    repo: Repo;
+    resolver: Resolver;
+}): Finding[];
+/**
+ * R23, full pass: each committed `contracts/<app>/schema.graphql` and `contracts/<app>/openapi.json` equals what `emit` writes for
+ * the app now. `emit({ repoRoot, declaration, outDir })` is `emitContracts` of packages/hfs/emit and answers `{ written, skipped }`;
+ * it is injected because the runtime scripts do not import the hfs package. Every api app is emitted on its own into a temp
+ * directory, so one app that cannot emit does not hide the others; an uncommitted emitted snapshot is a finding here too. Answers
+ * `{ findings, apps }`, `apps` being what was judged: `[{ app, artifact, status }]`, `artifact` being `schema.graphql` or
+ * `openapi.json` and `status` one of `fresh`, `stale`, `not-committed`, `none` (nothing emitted, nothing committed; GraphQL only),
+ * `left-behind` (committed, nothing emitted) or `emit-failed`.
+ */
+export declare function contractEmitFindings({ repoRoot, files, repo, emit }: {
+    repoRoot: string;
+    files: string[];
+    repo: Repo;
+    emit: Parsed;
+}): {
+    findings: Finding[];
+    apps: any[];
+};

package/runtime/scripts/hfs/rules/contract.mjs

@@ -14,125 +14,137 @@ import { found, readText } from './read.mjs';
 import { safeRemove } from '../../api/fs/safe-remove.mjs';
 import { makeTempDir } from '../../api/fs/make-temp-dir.mjs';
 import { loadTypescript } from '../../lib/package-at.mjs';
-
 const CONTRACT_SNAPSHOT_DRIFT = 'HFS_CONTRACT_SNAPSHOT_DRIFT';
 const GRAPHQL_TRANSPORT_SLOT = 'be.transport.graphql';
 const SNAPSHOT_OF = { graphql: 'schema.graphql', json: 'openapi.json' };
 const GRAPHQL_PLATFORM = /^src\/modules\/platform\/graphql(?:\/|\.ts$|$)/;
 const HERE = path.dirname(fileURLToPath(import.meta.url));
-
 /** A side-relative source import through a relative path or the canonical backend aliases. */
 function sourcePath(from, specifier) {
-  const alias = [['@modules/', 'src/modules/'], ['@features/', 'src/features/']].find(([prefix]) => specifier.startsWith(prefix));
-  let relative = null;
-  if (alias) relative = `${alias[1]}${specifier.slice(alias[0].length)}`;
-  else if (specifier.startsWith('.')) relative = path.posix.join(path.posix.dirname(from), specifier);
-  return relative === null ? null : path.posix.normalize(relative).replace(/\.js$/, '.ts');
+    const alias = [['@modules/', 'src/modules/'], ['@features/', 'src/features/']].find(([prefix]) => specifier.startsWith(prefix));
+    let relative = null;
+    if (alias)
+        relative = `${alias[1]}${specifier.slice(alias[0].length)}`;
+    else if (specifier.startsWith('.'))
+        relative = path.posix.join(path.posix.dirname(from), specifier);
+    return relative === null ? null : path.posix.normalize(relative).replace(/\.js$/, '.ts');
 }
-
 /** A tracked source file of an import, including directory entries and JavaScript-extension TypeScript imports. */
 function sourceOf(base, tracked) {
-  return [base, `${base}.ts`, `${base}/index.ts`].find(file => tracked.has(file)) ?? null;
+    return [base, `${base}.ts`, `${base}/index.ts`].find(file => tracked.has(file)) ?? null;
 }
-
 /** Runtime imports and re-exports, parsed by the same TypeScript loader as the neighbouring content rules. */
 function runtimeSpecifiers(ts, file, text) {
-  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-  const specifiers = [];
-  const visit = node => {
-    if (ts.isImportTypeNode(node)) return;
-    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
-      const clause = node.importClause ?? node;
-      const bindings = ts.isImportDeclaration(node) ? clause.namedBindings : node.exportClause;
-      const onlyTypes = clause.isTypeOnly || (!clause.name && bindings?.elements?.length && bindings.elements.every(item => item.isTypeOnly));
-      if (!onlyTypes && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) specifiers.push(node.moduleSpecifier.text);
-      return;
-    }
-    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteral(node.arguments[0])) specifiers.push(node.arguments[0].text);
-    ts.forEachChild(node, visit);
-  };
-  visit(source);
-  return specifiers;
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const specifiers = [];
+    const visit = (node) => {
+        if (ts.isImportTypeNode(node))
+            return;
+        if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+            const clause = ts.isImportDeclaration(node) ? node.importClause ?? node : node;
+            const bindings = ts.isImportDeclaration(node) ? clause.namedBindings : node.exportClause;
+            const onlyTypes = clause.isTypeOnly || (!clause.name && bindings?.elements?.length && bindings.elements.every((item) => item.isTypeOnly));
+            if (!onlyTypes && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier))
+                specifiers.push(node.moduleSpecifier.text);
+            return;
+        }
+        if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteral(node.arguments[0]))
+            specifiers.push(node.arguments[0].text);
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return specifiers;
 }
-
 /** The import closure of one app's composition, including its groups and the feature transports it owns. */
 function servesGraphql(app, tracked, classified, sources) {
-  if ([...classified.values()].some(file => file.slot === GRAPHQL_TRANSPORT_SLOT && file.bindings?.app === app.name)) return true;
-  const pending = [`apps/${app.name}/src/app.module.ts`];
-  const seen = new Set();
-  while (pending.length) {
-    const file = pending.pop();
-    if (seen.has(file) || !tracked.has(file)) continue;
-    seen.add(file);
-    if (classified.get(file)?.slot === GRAPHQL_TRANSPORT_SLOT) return true;
-    const bases = sources(file).map(specifier => sourcePath(file, specifier)).filter(base => base !== null);
-    if (bases.some(base => GRAPHQL_PLATFORM.test(base))) return true;
-    pending.push(...bases.map(base => sourceOf(base, tracked)).filter(Boolean));
-  }
-  return false;
+    if ([...classified.values()].some(file => file.slot === GRAPHQL_TRANSPORT_SLOT && file.bindings?.app === app.name))
+        return true;
+    const pending = [`apps/${app.name}/src/app.module.ts`];
+    const seen = new Set();
+    while (pending.length) {
+        const file = pending.pop();
+        if (seen.has(file) || !tracked.has(file))
+            continue;
+        seen.add(file);
+        if (classified.get(file)?.slot === GRAPHQL_TRANSPORT_SLOT)
+            return true;
+        const bases = sources(file).map((specifier) => sourcePath(file, specifier)).filter((base) => base !== null);
+        if (bases.some((base) => GRAPHQL_PLATFORM.test(base)))
+            return true;
+        pending.push(...bases.map((base) => sourceOf(base, tracked)).filter(Boolean));
+    }
+    return false;
 }
-
 /** sha256 of a file's text with line endings folded, or null when it cannot be read. */
 function contractHash(file) {
-  try { return createHash('sha256').update(fs.readFileSync(file, 'utf8').replaceAll('\r\n', '\n')).digest('hex'); } catch { return null; }
+    try {
+        return createHash('sha256').update(fs.readFileSync(file, 'utf8').replaceAll('\r\n', '\n')).digest('hex');
+    }
+    catch {
+        return null;
+    }
 }
-
 /** The findings of R23 for the be side at `repoRoot` (a side of another profile has none). */
 export function contractFindings({ repoRoot, files, repo, resolver }) {
-  const findings = [];
-  if (repo.profile !== 'be') return findings;
-  const tracked = new Set(files);
-  const classified = new Map(files.map(file => [file, resolver.classifyPath(file)]));
-  const ts = loadTypescript(repoRoot, HERE);
-  const imports = new Map();
-  const sources = file => {
-    if (!imports.has(file)) imports.set(file, ts ? runtimeSpecifiers(ts, file, readText(repoRoot, file) ?? '') : []);
-    return imports.get(file);
-  };
-  for (const app of repo.apps.filter((a) => a.kind === 'api')) {
-    const operations = `contracts/${app.name}/${SNAPSHOT_OF.json}`;
-    if (tracked.has(`apps/${app.name}/src/operations.ts`) && !tracked.has(operations)) findings.push(found(CONTRACT_SNAPSHOT_DRIFT, operations, `${app.name} declares an operation table (apps/${app.name}/src/operations.ts) but ${operations} is not committed; declare be.contract.openapi in hfs.json sides.be.optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
-    // Composition groups and transport ownership are app-specific: another service's GraphQL files do not apply here.
-    if (!servesGraphql(app, tracked, classified, sources)) continue;
-    const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
-    if (!tracked.has(snapshot)) findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${app.name} serves GraphQL but ${snapshot} is not committed; declare be.contract.graphql in hfs.json sides.be.optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
-  }
-  return findings;
+    const findings = [];
+    if (repo.profile !== 'be')
+        return findings;
+    const tracked = new Set(files);
+    const classified = new Map(files.map((file) => [file, resolver.classifyPath(file)]));
+    const ts = loadTypescript(repoRoot, HERE);
+    const imports = new Map();
+    const sources = (file) => {
+        if (!imports.has(file))
+            imports.set(file, ts ? runtimeSpecifiers(ts, file, readText(repoRoot, file) ?? '') : []);
+        return imports.get(file);
+    };
+    for (const app of repo.apps.filter((a) => a.kind === 'api')) {
+        const operations = `contracts/${app.name}/${SNAPSHOT_OF.json}`;
+        if (tracked.has(`apps/${app.name}/src/operations.ts`) && !tracked.has(operations))
+            findings.push(found(CONTRACT_SNAPSHOT_DRIFT, operations, `${app.name} declares an operation table (apps/${app.name}/src/operations.ts) but ${operations} is not committed; declare be.contract.openapi in hfs.json sides.be.optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
+        // Composition groups and transport ownership are app-specific: another service's GraphQL files do not apply here.
+        if (!servesGraphql(app, tracked, classified, sources))
+            continue;
+        const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
+        if (!tracked.has(snapshot))
+            findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${app.name} serves GraphQL but ${snapshot} is not committed; declare be.contract.graphql in hfs.json sides.be.optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
+    }
+    return findings;
 }
-
 /** The first lines of an error, enough to act on. */
 const errorText = (error) => String(error?.message ?? error).split(/\r?\n/).filter(Boolean).slice(0, 4).join(' | ');
-
 function emitFailure(app, artifacts, error, apps, findings) {
-  for (const { artifact } of artifacts) apps.push({ app: app.name, artifact, status: 'emit-failed' });
-  const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
-  findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `contracts/${app.name} cannot be verified: \`starci app emit\` failed for ${app.name}: ${errorText(error)}`, { app: app.name, drift: 'emit-failed' }));
+    for (const { artifact } of artifacts)
+        apps.push({ app: app.name, artifact, status: 'emit-failed' });
+    const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
+    findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `contracts/${app.name} cannot be verified: \`starci app emit\` failed for ${app.name}: ${errorText(error)}`, { app: app.name, drift: 'emit-failed' }));
 }
-
 function artifactFindings({ repoRoot, tracked, scratch, app, artifact, what, emitted, apps, findings }) {
-  const snapshot = `contracts/${app.name}/${artifact}`;
-  const committed = tracked.has(snapshot) ? contractHash(path.join(repoRoot, snapshot)) : null;
-  if (!emitted.written.includes(snapshot)) {
+    const snapshot = `contracts/${app.name}/${artifact}`;
+    const committed = tracked.has(snapshot) ? contractHash(path.join(repoRoot, snapshot)) : null;
+    if (!emitted.written.includes(snapshot)) {
+        if (committed === null) {
+            if (artifact === SNAPSHOT_OF.graphql)
+                apps.push({ app: app.name, artifact, status: 'none' });
+            return;
+        }
+        apps.push({ app: app.name, artifact, status: 'left-behind' });
+        findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} is committed but ${app.name} ${what}; delete it`, { app: app.name, drift: 'left-behind' }));
+        return;
+    }
+    const fresh = contractHash(path.join(scratch, snapshot));
     if (committed === null) {
-      if (artifact === SNAPSHOT_OF.graphql) apps.push({ app: app.name, artifact, status: 'none' });
-      return;
+        apps.push({ app: app.name, artifact, status: 'not-committed' });
+        findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${app.name} emits ${snapshot} but it is not committed or readable; run \`npm run contract:emit\` and commit the snapshot`, { app: app.name, drift: 'not-committed' }));
+    }
+    else if (committed === fresh) {
+        apps.push({ app: app.name, artifact, status: 'fresh' });
+    }
+    else {
+        apps.push({ app: app.name, artifact, status: 'stale' });
+        findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} (${committed.slice(0, 12)}) differs from what ${app.name} emits now (${String(fresh).slice(0, 12)}); run \`npm run contract:emit\` and commit the result`, { app: app.name, drift: 'stale' }));
     }
-    apps.push({ app: app.name, artifact, status: 'left-behind' });
-    findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} is committed but ${app.name} ${what}; delete it`, { app: app.name, drift: 'left-behind' }));
-    return;
-  }
-  const fresh = contractHash(path.join(scratch, snapshot));
-  if (committed === null) {
-    apps.push({ app: app.name, artifact, status: 'not-committed' });
-    findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${app.name} emits ${snapshot} but it is not committed or readable; run \`npm run contract:emit\` and commit the snapshot`, { app: app.name, drift: 'not-committed' }));
-  } else if (committed === fresh) {
-    apps.push({ app: app.name, artifact, status: 'fresh' });
-  } else {
-    apps.push({ app: app.name, artifact, status: 'stale' });
-    findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} (${committed.slice(0, 12)}) differs from what ${app.name} emits now (${String(fresh).slice(0, 12)}); run \`npm run contract:emit\` and commit the result`, { app: app.name, drift: 'stale' }));
-  }
 }
-
 /**
  * R23, full pass: each committed `contracts/<app>/schema.graphql` and `contracts/<app>/openapi.json` equals what `emit` writes for
  * the app now. `emit({ repoRoot, declaration, outDir })` is `emitContracts` of packages/hfs/emit and answers `{ written, skipped }`;
@@ -143,28 +155,31 @@ function artifactFindings({ repoRoot, tracked, scratch, app, artifact, what, emi
  * `left-behind` (committed, nothing emitted) or `emit-failed`.
  */
 export function contractEmitFindings({ repoRoot, files, repo, emit }) {
-  const findings = [];
-  const apps = [];
-  if (repo.profile !== 'be') return { findings, apps };
-  const tracked = new Set(files);
-  const scratch = makeTempDir('hfs-contracts-');
-  try {
-    for (const app of repo.apps.filter((a) => a.kind === 'api')) {
-      const artifacts = [{ artifact: SNAPSHOT_OF.graphql, what: 'serves no GraphQL any more' }, { artifact: SNAPSHOT_OF.json, what: 'declares no operations any more' }];
-      let emitted;
-      try {
-        emitted = emit({ repoRoot, declaration: { apps: [app] }, outDir: scratch });
-      } catch (error) {
-        emitFailure(app, artifacts, error, apps, findings);
-        continue;
-      }
-      for (const { artifact, what } of artifacts) {
-        artifactFindings({ repoRoot, tracked, scratch, app, artifact, what, emitted, apps, findings });
-      }
+    const findings = [];
+    const apps = [];
+    if (repo.profile !== 'be')
+        return { findings, apps };
+    const tracked = new Set(files);
+    const scratch = makeTempDir('hfs-contracts-');
+    try {
+        for (const app of repo.apps.filter((a) => a.kind === 'api')) {
+            const artifacts = [{ artifact: SNAPSHOT_OF.graphql, what: 'serves no GraphQL any more' }, { artifact: SNAPSHOT_OF.json, what: 'declares no operations any more' }];
+            let emitted;
+            try {
+                emitted = emit({ repoRoot, declaration: { apps: [app] }, outDir: scratch });
+            }
+            catch (error) {
+                emitFailure(app, artifacts, error, apps, findings);
+                continue;
+            }
+            for (const { artifact, what } of artifacts) {
+                artifactFindings({ repoRoot, tracked, scratch, app, artifact, what, emitted, apps, findings });
+            }
+        }
+    }
+    finally {
+        // A temp directory this rule made itself, in no ledger's repository: no indexed job artifact can live in it.
+        safeRemove(scratch, { hold: () => null });
     }
-  } finally {
-    // A temp directory this rule made itself, in no ledger's repository: no indexed job artifact can live in it.
-    safeRemove(scratch, { hold: () => null });
-  }
-  return { findings, apps };
+    return { findings, apps };
 }

package/runtime/scripts/hfs/rules/coverage-below.d.mts

@@ -0,0 +1,17 @@
+import type { Parsed, Repo } from './rule-types.mjs';
+export declare const HFS_COVERAGE_BELOW = "HFS_COVERAGE_BELOW";
+/**
+ * Read-only R273 report for an app or be side. `lcov` injects report text; `coverageFrom` selects a path relative to repoRoot.
+ * Only an explicit report enables the check; ordinary app check does not infer a stale report from coverage/lcov.info.
+ */
+export declare function coverageBelowReport({ repoRoot, files, all, repo, manifest, coverageFrom, lcov }?: {
+    repoRoot?: string;
+    files?: string[];
+    all?: string[];
+    repo?: Repo;
+    manifest?: Parsed;
+    coverageFrom?: string;
+    lcov?: string;
+}): Record<string, any>;
+/** Synchronous finder for the alpha.15 registry; explicit coverage reports may also be passed through extraFindings. */
+export declare const coverageBelowFindings: (context: Parsed) => any;