@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/hfs/rules/fe-contract-documents.mjs

@@ -12,147 +12,157 @@ import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
 import { isConstVariable, sourceLocation } from '../../lib/ts-ast.mjs';
 import { lexicalChecker } from '../../lib/ts-analysis.mjs';
-
 export const FE_GRAPHQL_CONTRACT = 'FE_GRAPHQL_CONTRACT';
-
 const CONTRACT = /^be\/contracts\/([^/]+)\/schema\.graphql$/;
 const isFrontend = (file) => file.startsWith('fe/') && !file.includes('/__generated__/') && !file.includes('/node_modules/');
 const isDocument = (file) => isFrontend(file) && file.endsWith('.graphql');
 const isSource = (file) => isFrontend(file) && /\.[cm]?[jt]sx?$/.test(file) && !file.endsWith('.d.ts');
 const HERE = fileURLToPath(new URL('.', import.meta.url));
-
 /** Local names of gql imports (including a graphql-tag default import), alongside the canonical gql spelling. */
 function addGqlImportNames(ts, statement, names) {
-  if (!ts.isImportDeclaration(statement)) return;
-  const clause = statement.importClause;
-  if (statement.moduleSpecifier.text === 'graphql-tag' && clause?.name) names.add(clause.name.text);
-  const bindings = clause?.namedBindings;
-  if (!bindings || !ts.isNamedImports(bindings)) return;
-  for (const entry of bindings.elements) {
-    if ((entry.propertyName ?? entry.name).text === 'gql') names.add(entry.name.text);
-  }
+    if (!ts.isImportDeclaration(statement))
+        return;
+    const clause = statement.importClause;
+    if (ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === 'graphql-tag' && clause?.name)
+        names.add(clause.name.text);
+    const bindings = clause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings))
+        return;
+    for (const entry of bindings.elements) {
+        if ((entry.propertyName ?? entry.name).text === 'gql')
+            names.add(entry.name.text);
+    }
 }
-
 function gqlNames(ts, source) {
-  const names = new Set(['gql']);
-  for (const statement of source.statements) addGqlImportNames(ts, statement, names);
-  return names;
+    const names = new Set(['gql']);
+    for (const statement of source.statements)
+        addGqlImportNames(ts, statement, names);
+    return names;
 }
-
 const isGqlTag = (ts, tag, names) => (ts.isIdentifier(tag) && names.has(tag.text)) || (ts.isPropertyAccessExpression(tag) && tag.name.text === 'gql');
-
 /** Resolve literal fragment substitutions without evaluating source code. Unknown or cyclic values cannot be judged. */
 function templateText(ts, node, checker, names, visiting = new Set()) {
-  if (ts.isStringLiteralLike(node)) return node.text;
-  if (ts.isIdentifier(node)) {
-    const symbol = checker.getSymbolAtLocation(node);
-    const declaration = symbol?.valueDeclaration;
-    if (symbol?.declarations?.length !== 1 || !declaration || !ts.isVariableDeclaration(declaration)
-      || !ts.isIdentifier(declaration.name) || !isConstVariable(ts, declaration) || !declaration.initializer || visiting.has(declaration)) return null;
-    return templateText(ts, declaration.initializer, checker, names, new Set([...visiting, declaration]));
-  }
-  if (ts.isTaggedTemplateExpression(node) && isGqlTag(ts, node.tag, names)) return templateText(ts, node.template, checker, names, visiting);
-  if (!ts.isTemplateExpression(node)) return null;
-  let text = node.head.text;
-  for (const span of node.templateSpans) {
-    const value = templateText(ts, span.expression, checker, names, visiting);
-    if (value === null) return null;
-    text += value + span.literal.text;
-  }
-  return text;
+    if (ts.isStringLiteralLike(node))
+        return node.text;
+    if (ts.isIdentifier(node)) {
+        const symbol = checker.getSymbolAtLocation(node);
+        const declaration = symbol?.valueDeclaration;
+        if (symbol?.declarations?.length !== 1 || !declaration || !ts.isVariableDeclaration(declaration)
+            || !ts.isIdentifier(declaration.name) || !isConstVariable(ts, declaration) || !declaration.initializer || visiting.has(declaration))
+            return null;
+        return templateText(ts, declaration.initializer, checker, names, new Set([...visiting, declaration]));
+    }
+    if (ts.isTaggedTemplateExpression(node) && isGqlTag(ts, node.tag, names))
+        return templateText(ts, node.template, checker, names, visiting);
+    if (!ts.isTemplateExpression(node))
+        return null;
+    let text = node.head.text;
+    for (const span of node.templateSpans) {
+        const value = templateText(ts, span.expression, checker, names, visiting);
+        if (value === null)
+            return null;
+        text += value + span.literal.text;
+    }
+    return text;
 }
-
 /** Actual tagged-template AST nodes: comments, quoted examples and other template tags are not operations. */
 function gqlDocuments(ts, file, text) {
-  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
-  const names = gqlNames(ts, source);
-  const templates = [];
-  const visit = (node) => {
-    if (ts.isTaggedTemplateExpression(node) && isGqlTag(ts, node.tag, names)) templates.push(node);
-    ts.forEachChild(node, visit);
-  };
-  visit(source);
-  if (templates.length === 0) return [];
-  const checker = lexicalChecker(ts, source);
-  return templates.map((node) => ({ text: templateText(ts, node.template, checker, names), ...sourceLocation(source, node) }));
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+    const names = gqlNames(ts, source);
+    const templates = [];
+    const visit = (node) => {
+        if (ts.isTaggedTemplateExpression(node) && isGqlTag(ts, node.tag, names))
+            templates.push(node);
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    if (templates.length === 0)
+        return [];
+    const checker = lexicalChecker(ts, source);
+    return templates.map((node) => ({ text: templateText(ts, node.template, checker, names), ...sourceLocation(source, node) }));
 }
-
 /** The parsed contracts of the app: [{ service, path, schema }], or a finding for a snapshot that does not parse. */
 function contractsOf(repoRoot, files, findings) {
-  const contracts = [];
-  for (const file of files) {
-    const match = CONTRACT.exec(file);
-    if (!match) continue;
-    const text = readText(repoRoot, file);
-    if (text === null) continue;
-    try {
-      contracts.push({ service: match[1], path: file, schema: parseSchema(text) });
-    } catch (error) {
-      findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file} is not a GraphQL schema the front-end documents can be judged against: ${error.message}. Run \`npm run contract:emit\`.`));
+    const contracts = [];
+    for (const file of files) {
+        const match = CONTRACT.exec(file);
+        if (!match)
+            continue;
+        const text = readText(repoRoot, file);
+        if (text === null)
+            continue;
+        try {
+            contracts.push({ service: match[1], path: file, schema: parseSchema(text) });
+        }
+        catch (error) {
+            findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file} is not a GraphQL schema the front-end documents can be judged against: ${error.message}. Run \`npm run contract:emit\`.`));
+        }
     }
-  }
-  return contracts;
+    return contracts;
 }
-
 function operationFindings(file, document, operation, contracts) {
-  const label = operation.name ?? `anonymous ${operation.operation}`;
-  const [first] = rootFieldsOf(operation);
-  const serving = contracts.filter(({ schema }) => schema.types.get(schema.roots[operation.operation])?.fields?.has(first));
-  if (serving.length === 0) {
-    const where = contracts.length === 0 ? 'the app keeps no be/contracts/<service>/schema.graphql' : `no contract of ${contracts.map((c) => c.path).join(', ')} declares ${operation.operation} ${first}`;
-    return [found(FE_GRAPHQL_CONTRACT, file, `${file}: ${label} asks ${operation.operation} ${first}, but ${where}; the front end sends only what a back end serves.`, { operation: label, service: null })];
-  }
-  const [contract] = serving;
-  const problems = operationProblems(contract.schema, document, operation);
-  if (problems.length > 0) return [found(FE_GRAPHQL_CONTRACT, file, `${file}: ${label} does not match the ${contract.service} contract (${contract.path}): ${problems.join('; ')}.`, { operation: label, service: contract.service, problems })];
-  return [];
+    const label = operation.name ?? `anonymous ${operation.operation}`;
+    const [first] = rootFieldsOf(operation);
+    const serving = contracts.filter(({ schema }) => schema.types.get(schema.roots[operation.operation])?.fields?.has(first));
+    if (serving.length === 0) {
+        const where = contracts.length === 0 ? 'the app keeps no be/contracts/<service>/schema.graphql' : `no contract of ${contracts.map((c) => c.path).join(', ')} declares ${operation.operation} ${first}`;
+        return [found(FE_GRAPHQL_CONTRACT, file, `${file}: ${label} asks ${operation.operation} ${first}, but ${where}; the front end sends only what a back end serves.`, { operation: label, service: null })];
+    }
+    const [contract] = serving;
+    const problems = operationProblems(contract.schema, document, operation);
+    if (problems.length > 0)
+        return [found(FE_GRAPHQL_CONTRACT, file, `${file}: ${label} does not match the ${contract.service} contract (${contract.path}): ${problems.join('; ')}.`, { operation: label, service: contract.service, problems })];
+    return [];
 }
-
 function documentFindings(file, text, contracts) {
-  let document;
-  try {
-    document = parseDocument(text);
-  } catch (error) {
-    return [found(FE_GRAPHQL_CONTRACT, file, `${file} is not a GraphQL document: ${error.message}.`)];
-  }
-  return document.operations.flatMap((operation) => operationFindings(file, document, operation, contracts));
+    let document;
+    try {
+        document = parseDocument(text);
+    }
+    catch (error) {
+        return [found(FE_GRAPHQL_CONTRACT, file, `${file} is not a GraphQL document: ${error.message}.`)];
+    }
+    return document.operations.flatMap((operation) => operationFindings(file, document, operation, contracts));
 }
-
 function sourceDocuments(ts, file, text, findings) {
-  if (!ts) {
-    findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file} gql templates cannot be judged: no TypeScript resolves from the app; install the app's dependencies.`));
-    return [];
-  }
-  const documents = [];
-  for (const template of gqlDocuments(ts, file, text)) {
-    if (template.text === null) findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file}:${template.line} gql template has a substitution that cannot be resolved to static GraphQL text.`, { line: template.line, column: template.column }));
-    else documents.push({ file, ...template });
-  }
-  return documents;
+    if (!ts) {
+        findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file} gql templates cannot be judged: no TypeScript resolves from the app; install the app's dependencies.`));
+        return [];
+    }
+    const documents = [];
+    for (const template of gqlDocuments(ts, file, text)) {
+        if (template.text === null)
+            findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file}:${template.line} gql template has a substitution that cannot be resolved to static GraphQL text.`, { line: template.line, column: template.column }));
+        else
+            documents.push({ file, ...template, text: template.text });
+    }
+    return documents;
 }
-
 function documentsOf(repoRoot, files, findings) {
-  const candidates = files.filter((file) => isDocument(file) || isSource(file)).sort(byCodeUnit);
-  const ts = candidates.some(isSource) ? loadTypescript(repoRoot, HERE) : null;
-  const documents = [];
-  for (const file of candidates) {
-    const text = readText(repoRoot, file);
-    if (text === null) continue;
-    if (isDocument(file)) documents.push({ file, text });
-    else documents.push(...sourceDocuments(ts, file, text, findings));
-  }
-  return documents;
+    const candidates = files.filter((file) => isDocument(file) || isSource(file)).sort(byCodeUnit);
+    const ts = candidates.some(isSource) ? loadTypescript(repoRoot, HERE) : null;
+    const documents = [];
+    for (const file of candidates) {
+        const text = readText(repoRoot, file);
+        if (text === null)
+            continue;
+        if (isDocument(file))
+            documents.push({ file, text });
+        else
+            documents.push(...sourceDocuments(ts, file, text, findings));
+    }
+    return documents;
 }
-
 /** The findings of R113 over the tracked paths `files` of the app at `repoRoot`. */
 export function feContractFindings({ repoRoot, files }) {
-  const findings = [];
-  const documents = documentsOf(repoRoot, files, findings);
-  if (documents.length === 0) return findings;
-  const contracts = contractsOf(repoRoot, files, findings);
-  for (const { file, text, line, column } of documents) {
-    const entries = documentFindings(file, text, contracts);
-    findings.push(...entries.map((entry) => line ? { ...entry, line, column } : entry));
-  }
-  return findings;
+    const findings = [];
+    const documents = documentsOf(repoRoot, files, findings);
+    if (documents.length === 0)
+        return findings;
+    const contracts = contractsOf(repoRoot, files, findings);
+    for (const { file, text, line, column } of documents) {
+        const entries = documentFindings(file, text, contracts);
+        findings.push(...entries.map((entry) => line ? { ...entry, line, column } : entry));
+    }
+    return findings;
 }

package/runtime/scripts/hfs/rules/fe-no-tests.d.mts

@@ -0,0 +1,9 @@
+export declare const FE_NO_TESTS = "FE_NO_TESTS";
+export declare const DEPENDENCY_SECTIONS: string[];
+/** True for a path FE_NO_TESTS owns: a spec file, a test directory or a test-tool file. */
+export declare const isFeTestPath: (file: string) => boolean;
+/** The findings of R97 over the tracked paths `files` of a front-end repository at `repoRoot`. */
+export declare function feNoTestsFindings({ repoRoot, files }: {
+    repoRoot: string;
+    files: string[];
+}): import("./rule-types.mjs").Finding[];

package/runtime/scripts/hfs/rules/fe-no-tests.mjs

@@ -8,60 +8,61 @@
 // The check reads the tracked tree and the manifests only. One finding per path (a manifest: one per script or dependency), and it is
 // the only finding of a test file: the slot check leaves these paths to it (isFeTestPath).
 import { found, readJson } from './read.mjs';
-
 export const FE_NO_TESTS = 'FE_NO_TESTS';
 const SPEC_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/;
 const TEST_DIRECTORY = /(?:^|\/)(?:e2e|__tests__|__mocks__|test-support)\//;
 const TEST_TOOL_FILE = /(?:^|\/)(?:(?:vitest|jest|playwright)\.[^/]+|cypress\.config\.[^/]+|tsconfig\.e2e\.json|e2e\.ya?ml)$/;
 const TEST_SCRIPT_NAME = /^(?:pre|post)?test(?::|$)/;
-const TEST_RUNNER_COMMAND_SOURCE = String.raw`(?:^|[\s&|;(])(?:npx\s+)?(?:vitest|jest|playwright|cypress|mocha)(?=$|[\s&|;)])|\bnode\s+(?:--\S+\s+)*--test\b`;
+const TEST_RUNNER_COMMAND_SOURCE = String.raw `(?:^|[\s&|;(])(?:npx\s+)?(?:vitest|jest|playwright|cypress|mocha)(?=$|[\s&|;)])|\bnode\s+(?:--\S+\s+)*--test\b`;
 const TEST_RUNNER_COMMAND = new RegExp(TEST_RUNNER_COMMAND_SOURCE);
-const TEST_DEPENDENCY_SOURCE = String.raw`^(?:vitest|@vitest\/.+|playwright|playwright-core|@playwright\/.+|jest|@jest\/.+|ts-jest|babel-jest|@types\/jest|jest-[\w-]+|mocha|@types\/mocha|cypress|@testing-library\/.+|jsdom|@types\/jsdom|happy-dom|axe-core|@axe-core\/.+|vitest-axe|@starci\/(?:vitest|jest|playwright)-preset)$`;
+const TEST_DEPENDENCY_SOURCE = String.raw `^(?:vitest|@vitest\/.+|playwright|playwright-core|@playwright\/.+|jest|@jest\/.+|ts-jest|babel-jest|@types\/jest|jest-[\w-]+|mocha|@types\/mocha|cypress|@testing-library\/.+|jsdom|@types\/jsdom|happy-dom|axe-core|@axe-core\/.+|vitest-axe|@starci\/(?:vitest|jest|playwright)-preset)$`;
 const TEST_DEPENDENCY = new RegExp(TEST_DEPENDENCY_SOURCE);
 export const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
-
 /** True for a path FE_NO_TESTS owns: a spec file, a test directory or a test-tool file. */
 export const isFeTestPath = (file) => SPEC_FILE.test(file) || TEST_DIRECTORY.test(file) || TEST_TOOL_FILE.test(file);
-
 function testPathFinding(file) {
-  let what = 'test tooling';
-  if (SPEC_FILE.test(file)) what = 'a test file';
-  else if (TEST_DIRECTORY.test(file)) what = 'inside a test directory';
-  return found(FE_NO_TESTS, file, `${file} is ${what}; a front-end repository has no tests, no test tooling and no exception: delete it`);
+    let what = 'test tooling';
+    if (SPEC_FILE.test(file))
+        what = 'a test file';
+    else if (TEST_DIRECTORY.test(file))
+        what = 'inside a test directory';
+    return found(FE_NO_TESTS, file, `${file} is ${what}; a front-end repository has no tests, no test tooling and no exception: delete it`);
 }
-
 function testDependencyFindings(file, pkg) {
-  const findings = [];
-  for (const section of DEPENDENCY_SECTIONS) {
-    for (const name of Object.keys(pkg[section] ?? {})) {
-      if (TEST_DEPENDENCY.test(name)) findings.push(found(FE_NO_TESTS, file, `${file} ${section} names ${name}, a test dependency; a front-end repository has no tests: delete the dependency`));
+    const findings = [];
+    for (const section of DEPENDENCY_SECTIONS) {
+        for (const name of Object.keys(pkg[section] ?? {})) {
+            if (TEST_DEPENDENCY.test(name))
+                findings.push(found(FE_NO_TESTS, file, `${file} ${section} names ${name}, a test dependency; a front-end repository has no tests: delete the dependency`));
+        }
     }
-  }
-  return findings;
+    return findings;
 }
-
 function packageTestFindings(repoRoot, file) {
-  if (file !== 'package.json' && !file.endsWith('/package.json')) return [];
-  if (file.includes('node_modules/')) return [];
-  const pkg = readJson(repoRoot, file);
-  if (!pkg || typeof pkg !== 'object') return [];
-  const findings = [];
-  for (const [name, command] of Object.entries(pkg.scripts ?? {})) {
-    if (TEST_SCRIPT_NAME.test(name) || TEST_RUNNER_COMMAND.test(String(command))) findings.push(found(FE_NO_TESTS, file, `${file} script ${name} is a test script (${String(command).slice(0, 80)}); a front-end repository has no tests: delete the script`));
-  }
-  findings.push(...testDependencyFindings(file, pkg));
-  return findings;
+    if (file !== 'package.json' && !file.endsWith('/package.json'))
+        return [];
+    if (file.includes('node_modules/'))
+        return [];
+    const pkg = readJson(repoRoot, file);
+    if (!pkg || typeof pkg !== 'object')
+        return [];
+    const findings = [];
+    for (const [name, command] of Object.entries(pkg.scripts ?? {})) {
+        if (TEST_SCRIPT_NAME.test(name) || TEST_RUNNER_COMMAND.test(String(command)))
+            findings.push(found(FE_NO_TESTS, file, `${file} script ${name} is a test script (${String(command).slice(0, 80)}); a front-end repository has no tests: delete the script`));
+    }
+    findings.push(...testDependencyFindings(file, pkg));
+    return findings;
 }
-
 /** The findings of R97 over the tracked paths `files` of a front-end repository at `repoRoot`. */
 export function feNoTestsFindings({ repoRoot, files }) {
-  const findings = [];
-  for (const file of files) {
-    if (isFeTestPath(file)) {
-      findings.push(testPathFinding(file));
-      continue;
+    const findings = [];
+    for (const file of files) {
+        if (isFeTestPath(file)) {
+            findings.push(testPathFinding(file));
+            continue;
+        }
+        findings.push(...packageTestFindings(repoRoot, file));
     }
-    findings.push(...packageTestFindings(repoRoot, file));
-  }
-  return findings;
+    return findings;
 }

package/runtime/scripts/hfs/rules/fe-stack.d.mts

@@ -0,0 +1,23 @@
+import type { Parsed, Repo } from './rule-types.mjs';
+export declare const FE_STACK_FORBIDDEN = "FE_STACK_FORBIDDEN";
+export declare const FE_STACK_UNLISTED = "FE_STACK_UNLISTED";
+export declare const FE_STACK_CORE_MISSING = "FE_STACK_CORE_MISSING";
+export declare const FE_STACK_FAMILY_LINT_MISSING = "FE_STACK_FAMILY_LINT_MISSING";
+/**
+ * FE_STACK_FORBIDDEN over the tracked paths `files` of one scope: every package.json of the fe side, or the app root's one
+ * package.json minus what the back end owns. A be side has no front-end manifest and answers [].
+ */
+export declare function feStackFindings({ repoRoot, files, repo, manifest }: {
+    repoRoot: string;
+    files: string[];
+    repo: Repo;
+    manifest: Parsed;
+}): import("./rule-types.mjs").Finding[];
+/** Closed FE catalog and core presence over the front-end side (the mixed root also holds BE tools). */
+export declare function feStackAllowlistFindings({ repoRoot, files, all, repo, inScope }: {
+    repoRoot: string;
+    files: string[];
+    all?: string[];
+    repo: Repo;
+    inScope?: (file: string) => boolean;
+}): import("./rule-types.mjs").Finding[];