@starci/eslint-canon-fe 8.2.18 → 8.3.0

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

@@ -323,6 +323,12 @@ function runtimeParamProblems(rp) {
   ];
 }
 
+const folderKindsValid = list => strList(list) && list.length > 0 && new Set(list).size === list.length && list.every(kind => NAME.test(kind));
+const kindPairValid = pair => isPlainObject(pair) && Object.keys(pair).sort(byCodeUnit).join() === 'from,to'
+  && ['from', 'to'].every(side => folderKindsValid(pair[side]));
+const kindRestrictionValid = kinds => isPlainObject(kinds) && Object.keys(kinds).length > 0
+  && Object.entries(kinds).every(([target, pair]) => NAME.test(target) && kindPairValid(pair));
+
 /** Shape problems of the tier map of one profile. */
 export function tierMapProblems(profile, tiers) {
   const bad = [];
@@ -330,14 +336,33 @@ export function tierMapProblems(profile, tiers) {
   for (const [tier, def] of Object.entries(tiers)) {
     if (!NAME.test(tier)) bad.push(`tiers.${profile}.${tier} is not a tier name`);
     if (!isPlainObject(def) || !Array.isArray(def.mayImport) || !def.mayImport.every((t) => NAME.test(String(t)))) bad.push(`tiers.${profile}.${tier}.mayImport must be a list of tier names`);
-    for (const key of Object.keys(def ?? {})) if (!['mayImport', 'acyclic', 'lowerLayerOnly'].includes(key)) bad.push(`tiers.${profile}.${tier}.${key} is not a tier field`);
+    if (def?.mayImportKinds !== undefined && !kindRestrictionValid(def.mayImportKinds)) bad.push(`tiers.${profile}.${tier}.mayImportKinds must map tier names to {from, to} non-empty lists of unique folder kinds`);
+    for (const key of Object.keys(def ?? {})) if (!['mayImport', 'mayImportKinds', 'acyclic', 'lowerLayerOnly'].includes(key)) bad.push(`tiers.${profile}.${tier}.${key} is not a tier field`);
+  }
+  return bad;
+}
+
+function tierFolderKindProblems(manifest, profile, tier, kinds, at) {
+  const known = new Set(manifest.slots.filter((slot) => slot.profiles.includes(profile) && slot.tier === tier).flatMap((slot) => [...(slot.kinds ?? []), ...(slot.layers ?? [])]));
+  return kinds.filter(kind => !known.has(kind)).map(kind => `${at} names ${kind}, which is not a folder kind of the ${tier} tier`);
+}
+
+/** Kind restrictions narrow an allowed tier edge and name kinds that its source and target slots actually declare. */
+export function tierKindProblems(manifest, profile) {
+  const bad = [];
+  for (const [tier, def] of Object.entries(manifest.tiers[profile])) {
+    for (const [target, kinds] of Object.entries(def.mayImportKinds ?? {})) {
+      const at = `tiers.${profile}.${tier}.mayImportKinds.${target}`;
+      if (!def.mayImport.includes(target)) bad.push(`${at} restricts a tier that mayImport does not allow`);
+      bad.push(...tierFolderKindProblems(manifest, profile, tier, kinds.from, `${at}.from`), ...tierFolderKindProblems(manifest, profile, target, kinds.to, `${at}.to`));
+    }
   }
   return bad;
 }
 
 /** The semantic rules of a runtime manifest beyond the slot rules both kinds share: tier names and the schema major. */
 export function runtimeSemanticProblems(m) {
-  const bad = [];
+  const bad = tierKindProblems(m, RUNTIME_KIND);
   const tiers = m.tiers.runtime;
   for (const [tier, def] of Object.entries(tiers)) {
     for (const target of def.mayImport) if (!(target in tiers)) bad.push(`tiers.runtime.${tier}.mayImport names ${target}, which is not a runtime tier`);

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

@@ -3,6 +3,7 @@
 // (scripts/hfs/project-graph.mjs) runs it over the same tree and serves the findings on a TypeScript file as ESLint reports.
 //   HFS_SLOT_UNDECLARED / HFS_SLOT_AMBIGUOUS / HFS_SLOT_NOT_ENABLED / HFS_FORBIDDEN_PRESENT / HFS_TOOL_CONFIG_LOCAL / HFS_TRACKED_MUST_BE_IGNORED (R01, R16)
 //   BE_SOURCE_FORM (R89, the file name), BE_SPEC_PLACEMENT (R102)
+import fs from 'node:fs';
 import path from 'node:path';
 import { allowsFile } from './allows.mjs';
 import { isFeTestPath } from './rules/fe-no-tests.mjs';
@@ -30,8 +31,11 @@ function sourceFormContext(file, resolver, suffixes, bannedSuffixes) {
   const slot = resolver.slot(c.slot);
   if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].includes(base)) return null;
   const admitted = allowsFile(resolver, file);
+  // Environment parsing is an app slot role, not a source suffix admitted outside that matching app file.
+  if (c.slot.startsWith('be.app.') && admitted?.allowed && admitted.entry === '<app>.env.ts') return null;
   if (admitted?.allowed && admitted.entry?.includes('/') && path.posix.basename(admitted.entry) === base) return null;
-  if (admitted?.allowed && PLAIN_ENTRY.test(admitted.entry ?? '') && KEBAB.test(base.slice(0, -'.ts'.length))) return null;
+  // A plain entry names its file by a variable only (`<x>.ts`, or `compose/<area>.ts` of an app slot): a kebab name is its form.
+  if (admitted?.allowed && PLAIN_ENTRY.test(path.posix.basename(admitted.entry ?? '')) && KEBAB.test(base.slice(0, -'.ts'.length))) return null;
   if (c.slot === 'be.persistence' && path.posix.basename(path.posix.dirname(file)) === 'migrations') return null;
   return { c, base, suffixes, bannedSuffixes };
 }
@@ -54,7 +58,7 @@ function sourceFormFinding(file, { c, base, suffixes, bannedSuffixes }, boundSuf
 
 /**
  * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, a migration of
- * be.persistence, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
+ * be.persistence, the matching <app>.env.ts explicitly admitted by its app slot, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
  * as order.service.spec.ts keeps its inner words kebab-case). A suffix of ruleParams.be.bannedSuffixes anywhere in the
  * name is refused by name. Paths no slot owns are HFS_SLOT_UNDECLARED's, not this code's.
  */
@@ -86,6 +90,8 @@ function forbiddenPathFinding(file, c, resolver) {
 }
 
 function pathStatusFinding(file, resolver) {
+  const liteWork = liteStarciworkFinding(file, resolver);
+  if (liteWork) return liteWork;
   const c = resolver.classifyPath(file);
   if (c.status === 'no-slot') {
     const nearestNote = c.nearest ? `; nearest slot ${c.nearest.slot} (${c.nearest.pattern}), matched ${c.nearest.matchedPrefix || '.'} then expected ${c.nearest.expectedNext ?? 'nothing'}` : '';
@@ -98,6 +104,30 @@ function pathStatusFinding(file, resolver) {
   return null;
 }
 
+/** The lite Work boundary, read from app.starciwork's edition-specific admission list, including paths a narrower slot owns. */
+export function liteStarciworkFinding(file, resolver, { dir = false } = {}) {
+  if (resolver.repo?.edition !== 'lite' || !resolver.slot('app.starciwork')) return null;
+  const p = resolver.classifyPath(file).path;
+  if (!p.startsWith('.starciwork/')) return null;
+  const admitted = allowsFile(resolver, dir ? `${p}/.probe` : p);
+  if (admitted?.slot === 'app.starciwork' && admitted.allowed) return null;
+  return { code: 'HFS_STARCIWORK_LITE_FORBIDDEN', level: 'error', path: p, slot: 'app.starciwork', message: `${p}: lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore); remove this path or use the full edition` };
+}
+
+/** Local lite Work leftovers, including metadata ignored by an old full-edition .gitignore. */
+export function liteStarciworkTreeFindings(repoRoot, resolver, tracked) {
+  if (resolver.repo?.edition !== 'lite' || !resolver.slot('app.starciwork')) return [];
+  let entries = [];
+  try { entries = fs.readdirSync(path.join(repoRoot, '.starciwork'), { withFileTypes: true }); } catch { /* Work is optional. */ }
+  const trackedSet = new Set(tracked);
+  return entries.flatMap(entry => {
+    const file = `.starciwork/${entry.name}`;
+    if (trackedSet.has(file)) return [];
+    const finding = liteStarciworkFinding(file, resolver, { dir: entry.isDirectory() });
+    return finding ? [finding] : [];
+  });
+}
+
 /** The findings of the slot manifest over `files` (repository-relative tracked paths) of a repository of `profile`. */
 export function pathFindings({ files, resolver, profile }) {
   const findings = [];

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

@@ -5,6 +5,8 @@
 //   - a tracked `.enc` that is not a sops envelope (an encrypted-looking file that holds plaintext);
 //   - a line of any other tracked text file that matches a secret pattern.
 // A finding names the file, the line and the pattern, never the value.
+import fs from 'node:fs';
+import path from 'node:path';
 import { FORBIDDEN_FILES, secretHits } from '../../lib/secret-patterns.mjs';
 import { isSopsEnvelope } from '../../lib/sops-envelope.mjs';
 import { found, readText } from './read.mjs';
@@ -16,6 +18,17 @@ const NOT_SCANNED = /(^|\/)package-lock\.json$/;
 /** True when the slot `id` of the manifest reports HFS_PLAINTEXT_SECRET for the paths it forbids. */
 export const slotOwnsSecrets = (slot) => slot?.rules?.includes(PLAINTEXT_SECRET) === true;
 
+/** A legacy lite root secrets.env is reported even when ignored; its presence is enough, so no value is read. */
+export function untrackedSecretFindings({ repoRoot, files, repo }) {
+  if (repo.profile !== 'app' || repo.edition !== 'lite' || files.includes('secrets.env')) return [];
+  try {
+    if (!fs.statSync(path.join(repoRoot, 'secrets.env')).isFile()) return [];
+  } catch {
+    return [];
+  }
+  return [found(PLAINTEXT_SECRET, 'secrets.env', 'secrets.env is an untracked plaintext secret at the lite app root; seal it with starci app secret set into .starcistacks/<env>/secrets/<slug>.enc and remove the plaintext file; read materialized values by *_FILE', { level: 'warning', pattern: 'untracked-secrets-env' })];
+}
+
 /**
  * The findings of R06 for one tracked file that no forbidden slot claims: a secret by being (an env file, a key file), an `.enc` that is
  * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too

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

@@ -65,8 +65,10 @@ export function importAllowedIn(scope, fromPath, toPath) {
   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] ?? {};
+  const { mayImport, mayImportKinds } = scope.manifest.tiers[scope.profile][fromTier] ?? {};
   if (!mayImport?.includes(toTier)) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport: mayImport ?? [] };
+  const kindRestriction = mayImportKinds?.[toTier];
+  if (kindRestriction && (!kindRestriction.from.includes(from.kind) || !kindRestriction.to.includes(to.kind))) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport, kindRestriction, fromKind: from.kind ?? null, toKind: to.kind ?? null };
   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.

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

@@ -5,6 +5,19 @@ import { braceVariants } from '../lib/glob.mjs';
 import { classifyIn, slotEnabled } from './slot-classify.mjs';
 import { fillVars, varsOf } from './slot-match.mjs';
 
+/** A populated fe.modules instance needs its index.ts only when it contains TypeScript, including nested files. */
+export function requiredFileApplies(slotId, target, files) {
+  if (!/^fe\.modules(?:\.|$)/u.test(slotId) || path.posix.basename(target) !== 'index.ts') return true;
+  const prefix = `${path.posix.dirname(target)}/`;
+  let populated = false;
+  for (const file of files) {
+    if (!file.startsWith(prefix)) continue;
+    populated = true;
+    if (/\.tsx?$/u.test(file)) return true;
+  }
+  return !populated;
+}
+
 /** 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('/');

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

@@ -2,7 +2,7 @@
 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 { manifestKind, RUNTIME_KIND, runtimeSemanticProblems, tierKindProblems } from './manifest-shape.mjs';
 import { APP_SCOPE, PROFILES } from './slot-manifest-shape.mjs';
 
 function checkAppRootSlot(slot, bad) {
@@ -113,6 +113,7 @@ function checkSideReads(manifest, bad, braceVariants) {
 }
 
 function checkProfileTierTargets(manifest, profile, bad) {
+  bad.push(...tierKindProblems(manifest, profile));
   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`);

package/runtime/scripts/lib/ts-analysis.mjs

@@ -0,0 +1,20 @@
+/** The expression under the wrappers selected by an AST check's contract. */
+export function unwrapExpression(ts, expression, { awaitExpressions = false, typeAssertions = true, satisfiesExpressions = true } = {}) {
+  while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
+    || (typeAssertions && ts.isTypeAssertionExpression(expression)) || ts.isNonNullExpression(expression)
+    || (satisfiesExpressions && (ts.isSatisfiesExpression?.(expression) ?? false))
+    || (awaitExpressions && ts.isAwaitExpression(expression)))) expression = expression.expression;
+  return expression;
+}
+
+/** Local name -> imported name and module; callers select their existing module key and literal policy. */
+export function importsOf(ts, sourceFile, { moduleKey = 'module', stringLiteralsOnly = false } = {}) {
+  const imports = new Map();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || (stringLiteralsOnly && !ts.isStringLiteralLike(statement.moduleSpecifier))) continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const binding of bindings.elements) imports.set(binding.name.text, { name: (binding.propertyName ?? binding.name).text, [moduleKey]: statement.moduleSpecifier.text });
+  }
+  return imports;
+}

package/size-and-state-budget.mjs

@@ -21,7 +21,7 @@
 import { functionOf, isFn } from "./lib/bindings.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
 import { isPromiseValued } from "./lib/types.mjs"
-import { fileOf, roleOfFile, slotOfFile } from "./lib/scope.mjs"
+import { baseName, fileOf, roleOfFile, slotOfFile } from "./lib/scope.mjs"
 
 /**
  * The budget the slot of the linted file states (`budget` in knowledge/hfs/slots.yaml), or an empty one when no slot owns the file
@@ -34,13 +34,17 @@ const budgetOf = (context) => {
 
 /**
  * The line limit of the linted file: the budget keyed by the file name its role has in the slot (`component.tsx` for the drawing,
- * `index.tsx` for the entry), else the slot's `file` budget (hooks 200, modules 400), else null.
+ * `index.tsx` for the entry), else the slot's `file` budget (hooks 200, modules 400), else null. A pure re-export `index.ts`
+ * uses the slot's separate `barrel` budget when stated: every statement must be an `export ... from` declaration.
  */
-const lineBudgetOf = (context) => {
+const lineBudgetOf = (context, node) => {
   const role = roleOfFile(context)
   const id = slotOfFile(context)
   const fileName = role === null || id === null ? undefined : hfsOf(context).slot(id)?.roles?.[role]
   const budget = budgetOf(context)
+  const pureBarrel = baseName(fileOf(context)) === "index.ts" && node.body.length > 0 && node.body.every((statement) =>
+    ["ExportNamedDeclaration", "ExportAllDeclaration"].includes(statement.type) && Boolean(statement.source))
+  if (pureBarrel && typeof budget.barrel === "number") return budget.barrel
   const limit = fileName !== undefined && typeof budget[fileName] === "number" ? budget[fileName] : budget.file
   return typeof limit === "number" ? limit : null
 }
@@ -73,11 +77,11 @@ const isUnitName = (name) => Boolean(name) && (/^[A-Z]/.test(name) || /^use[A-Z0
 
 // -- BUDGET-1 --------------------------------------------------------------------------------------
 
-/** A file is within the line budget its slot states for its role (`component.tsx`, `index.tsx`) or for every file (`file`). */
+/** A file is within the line budget its slot states for its role, pure re-export barrel (`barrel`) or every file (`file`). */
 export const componentLineBudget = {
   meta: {
     type: "suggestion",
-    docs: { description: "A file stays within the line budget its slot states (`component.tsx`, `index.tsx`, `file`)." },
+    docs: { description: "A file stays within the line budget its slot states (`component.tsx`, `index.tsx`, `barrel`, `file`)." },
     schema: [],
     messages: {
       lines:
@@ -85,12 +89,11 @@ export const componentLineBudget = {
     },
   },
   create(context) {
-    // A spec is not held to a budget; a file has one when its role or its slot states it.
-    const max = lineBudgetOf(context)
-    if (max === null) return {}
     const source = context.sourceCode || context.getSourceCode()
     return {
       Program(node) {
+        const max = lineBudgetOf(context, node)
+        if (max === null) return
         // A trailing newline is not a line of code.
         const count = source.lines.length - (source.lines[source.lines.length - 1] === "" ? 1 : 0)
         if (count > max) context.report({ node, messageId: "lines", data: { count, max } })