@sha3/code 1.0.0

package/lib/verify/error-handling-verifier.mjs

@@ -0,0 +1,164 @@
+import ts from "typescript";
+
+import { createContractIssue, getActiveVerifyRuleIds, shouldRunRule } from "./issue-helpers.mjs";
+import { getLineAndColumn } from "./source-analysis.mjs";
+
+const GENERIC_ERROR_MESSAGE_PATTERN = /^(error|failed|invalid|unexpected|oops|bad request)$/i;
+
+function createIssue(contract, ruleId, relativePath, node, message, options = {}) {
+  const location = node && "getStart" in node && "getSourceFile" in node ? getLineAndColumn(node.getSourceFile(), node.getStart(node.getSourceFile())) : {};
+  return createContractIssue(contract, {
+    ruleId,
+    category: "error-handling",
+    relativePath,
+    line: location.line,
+    column: location.column,
+    message,
+    verificationMode: options.verificationMode,
+    confidence: options.confidence,
+    evidence: options.evidence,
+    suggestion: options.suggestion,
+  });
+}
+
+function extendsError(node) {
+  if (!node.heritageClauses) {
+    return false;
+  }
+
+  return node.heritageClauses.some(
+    (clause) => clause.token === ts.SyntaxKind.ExtendsKeyword && clause.types.some((typeNode) => typeNode.expression.getText() === "Error"),
+  );
+}
+
+function collectTypedErrors(sourceFiles) {
+  const typedErrors = new Map();
+
+  for (const file of sourceFiles) {
+    ts.forEachChild(file.ast, (node) => {
+      if (ts.isClassDeclaration(node) && node.name && extendsError(node)) {
+        typedErrors.set(node.name.text, { file, node });
+      }
+    });
+  }
+
+  return typedErrors;
+}
+
+function collectErrorConsumers(sourceFiles) {
+  const consumers = new Set();
+
+  for (const file of sourceFiles) {
+    function visit(node) {
+      if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.InstanceOfKeyword && ts.isIdentifier(node.right)) {
+        consumers.add(node.right.text);
+      }
+
+      ts.forEachChild(node, visit);
+    }
+
+    visit(file.ast);
+  }
+
+  return consumers;
+}
+
+function hasMeaningfulCatchHandling(catchClause) {
+  if (!catchClause.block.statements.length) {
+    return false;
+  }
+
+  return catchClause.block.statements.some((statement) => {
+    if (ts.isThrowStatement(statement)) {
+      return true;
+    }
+
+    if (ts.isExpressionStatement(statement) && ts.isCallExpression(statement.expression) && ts.isPropertyAccessExpression(statement.expression.expression)) {
+      const propertyName = statement.expression.expression.name.text;
+      return propertyName === "error" || propertyName === "warn" || propertyName === "catch";
+    }
+
+    return false;
+  });
+}
+
+function readThrownErrorMessage(expression) {
+  if (
+    ts.isNewExpression(expression) &&
+    ts.isIdentifier(expression.expression) &&
+    expression.arguments?.length === 1 &&
+    ts.isStringLiteralLike(expression.arguments[0])
+  ) {
+    return expression.arguments[0].text;
+  }
+
+  return null;
+}
+
+export async function verifyErrorHandling(_targetPath, contract, analysisContext, options = {}) {
+  const activeRuleIds = getActiveVerifyRuleIds(contract);
+  const typedErrors = collectTypedErrors(analysisContext.sourceFiles);
+  const errorConsumers = collectErrorConsumers(analysisContext.sourceFiles);
+  const issues = [];
+
+  for (const file of analysisContext.sourceFiles) {
+    function visit(node) {
+      if (
+        activeRuleIds.has("no-silent-catch") &&
+        shouldRunRule(options.onlyRuleIds, "no-silent-catch") &&
+        ts.isCatchClause(node) &&
+        !hasMeaningfulCatchHandling(node)
+      ) {
+        issues.push(
+          createIssue(
+            contract,
+            "no-silent-catch",
+            file.relativePath,
+            node,
+            "catch blocks must rethrow, transform, or report errors with throw, console.warn, console.error, or promise-style .catch handling",
+          ),
+        );
+      }
+
+      if (
+        activeRuleIds.has("actionable-error-messages") &&
+        shouldRunRule(options.onlyRuleIds, "actionable-error-messages") &&
+        ts.isThrowStatement(node) &&
+        node.expression
+      ) {
+        const errorMessage = readThrownErrorMessage(node.expression);
+        if (errorMessage !== null && (errorMessage.trim().length === 0 || GENERIC_ERROR_MESSAGE_PATTERN.test(errorMessage.trim()))) {
+          issues.push(
+            createIssue(contract, "actionable-error-messages", file.relativePath, node.expression, "error messages should include actionable context", {
+              verificationMode: "heuristic",
+              confidence: "medium",
+              evidence: JSON.stringify(errorMessage),
+            }),
+          );
+        }
+      }
+
+      ts.forEachChild(node, visit);
+    }
+
+    visit(file.ast);
+  }
+
+  if (activeRuleIds.has("typed-error-must-be-used") && shouldRunRule(options.onlyRuleIds, "typed-error-must-be-used")) {
+    for (const [errorName, descriptor] of typedErrors) {
+      if (!errorConsumers.has(errorName)) {
+        issues.push(
+          createIssue(
+            contract,
+            "typed-error-must-be-used",
+            descriptor.file.relativePath,
+            descriptor.node.name,
+            `custom error ${errorName} must have a real discriminating consumer such as instanceof`,
+          ),
+        );
+      }
+    }
+  }
+
+  return issues;
+}

package/lib/verify/explain-rule.mjs

@@ -0,0 +1,54 @@
+function renderProfileOverrides(profileOverrides) {
+  if (!profileOverrides || profileOverrides.length === 0) {
+    return "- none";
+  }
+
+  return profileOverrides
+    .map((override) => {
+      if (override.equals !== undefined) {
+        return `- ${override.key} == ${String(override.equals)}`;
+      }
+
+      if (Array.isArray(override.oneOf)) {
+        return `- ${override.key} in [${override.oneOf.map((value) => String(value)).join(", ")}]`;
+      }
+
+      return `- ${override.key}`;
+    })
+    .join("\n");
+}
+
+function renderExamples(label, examples) {
+  if (!examples || examples.length === 0) {
+    return `${label}:\n- none`;
+  }
+
+  return `${label}:\n${examples.map((examplePath) => `- ${examplePath}`).join("\n")}`;
+}
+
+export function explainRule(rule) {
+  return `Rule: ${rule.id}
+Title: ${rule.title}
+Summary: ${rule.summary}
+Kind: ${rule.kind}
+Severity: ${rule.severity}
+Deterministic: ${rule.deterministic ? "yes" : "no"}
+Verification mode: ${rule.verificationMode}
+Verification source: ${rule.verificationSource}
+Confidence: ${rule.confidence}
+Applies to:
+${rule.appliesTo.map((pattern) => `- ${pattern}`).join("\n")}
+
+Enforced by:
+${rule.enforcedBy.map((enforcedBy) => `- ${enforcedBy}`).join("\n")}
+
+Implemented by:
+${(rule.implementedBy ?? []).map((implementedBy) => `- ${implementedBy}`).join("\n")}
+
+Profile overrides:
+${renderProfileOverrides(rule.profileOverrides)}
+
+Examples:
+${renderExamples("Good", rule.examples.good)}
+${renderExamples("Bad", rule.examples.bad)}`;
+}

package/lib/verify/issue-helpers.mjs

@@ -0,0 +1,132 @@
+import path from "node:path";
+
+export const PROJECT_VERIFY_RULE_IDS = [
+  "contract-presence",
+  "metadata-sync",
+  "managed-files",
+  "typescript-only",
+  "template-layout",
+  "readme-sections",
+  "readme-public-api",
+  "readme-public-methods",
+  "readme-http-api",
+  "readme-usage-examples",
+  "adapter-presence",
+];
+
+export const FAILURE_SEVERITIES = new Set(["error"]);
+export const STRICT_FAILURE_SEVERITIES = new Set(["error", "warning"]);
+
+export function createVerificationIssue(options) {
+  const issue = {
+    ruleId: options.ruleId,
+    category: options.category,
+    severity: options.severity ?? "error",
+    message: options.message,
+    enforcedBy: "verify",
+    verificationMode: options.verificationMode ?? "deterministic",
+    confidence: options.confidence ?? "high",
+  };
+
+  if (options.relativePath) {
+    issue.relativePath = options.relativePath;
+  }
+
+  if (typeof options.line === "number") {
+    issue.line = options.line;
+  }
+
+  if (typeof options.column === "number") {
+    issue.column = options.column;
+  }
+
+  if (options.evidence) {
+    issue.evidence = options.evidence;
+  }
+
+  if (options.suggestion) {
+    issue.suggestion = options.suggestion;
+  }
+
+  return issue;
+}
+
+export function shouldRunRule(onlyRuleIds, ruleId) {
+  if (!onlyRuleIds || onlyRuleIds.length === 0) {
+    return true;
+  }
+
+  return onlyRuleIds.includes(ruleId);
+}
+
+export function getRuleMap(contract, predicate = () => true) {
+  return new Map(contract.rules.filter(predicate).map((rule) => [rule.id, rule]));
+}
+
+export function getVerifyRuleMap(contract) {
+  return getRuleMap(contract, (rule) => rule.enforcedBy.includes("verify"));
+}
+
+export function getActiveVerifyRuleIds(contract) {
+  return new Set(getVerifyRuleMap(contract).keys());
+}
+
+export function getRuleSeverity(contract, ruleId, fallbackSeverity = "error") {
+  return getVerifyRuleMap(contract).get(ruleId)?.severity ?? fallbackSeverity;
+}
+
+export function createContractIssue(contract, options) {
+  return createVerificationIssue({
+    ...options,
+    severity: options.severity ?? getRuleSeverity(contract, options.ruleId),
+  });
+}
+
+export function normalizeRequestedFiles(targetPath, files) {
+  if (!files || files.length === 0) {
+    return [];
+  }
+
+  const normalizedFiles = new Set();
+
+  for (const rawFile of files) {
+    const resolvedPath = path.isAbsolute(rawFile) ? rawFile : path.resolve(targetPath, rawFile);
+    const relativePath = path.relative(targetPath, resolvedPath).split(path.sep).join("/");
+
+    if (relativePath.length === 0 || relativePath === ".") {
+      continue;
+    }
+
+    normalizedFiles.add(relativePath);
+  }
+
+  return [...normalizedFiles].sort((left, right) => left.localeCompare(right));
+}
+
+export function isFileSelected(selectedFiles, relativePath) {
+  if (!selectedFiles || selectedFiles.length === 0) {
+    return true;
+  }
+
+  return selectedFiles.includes(relativePath);
+}
+
+export function buildVerificationResult(issues, checkedRuleIds, checkedFiles, options = {}) {
+  const failureSeverities = options.failureSeverities ?? (options.strict ? STRICT_FAILURE_SEVERITIES : FAILURE_SEVERITIES);
+  const errorCount = issues.filter((issue) => issue.severity === "error").length;
+  const warningCount = issues.filter((issue) => issue.severity === "warning").length;
+  const auditCount = issues.filter((issue) => issue.severity === "audit").length;
+  return {
+    ok: !issues.some((issue) => failureSeverities.has(issue.severity)),
+    hasWarnings: warningCount > 0,
+    issues,
+    summary: {
+      issueCount: issues.length,
+      errorCount,
+      warningCount,
+      auditCount,
+      checkedRuleIds: [...new Set(checkedRuleIds)].sort((left, right) => left.localeCompare(right)),
+      checkedFiles: [...new Set(checkedFiles)].sort((left, right) => left.localeCompare(right)),
+    },
+  };
+}

package/lib/verify/project-layout-verifier.mjs

@@ -0,0 +1,259 @@
+import path from "node:path";
+
+import ts from "typescript";
+
+import { createContractIssue, getActiveVerifyRuleIds, shouldRunRule } from "./issue-helpers.mjs";
+import { resolveImportRelativePath } from "./source-analysis.mjs";
+
+const RESERVED_ROOT_SOURCE_FILES = new Set(["config.ts", "index.ts", "logger.ts", "main.ts"]);
+const RESERVED_FEATURE_FOLDERS = new Set(["app", "shared", "http", "public", "internal"]);
+const AMBIGUOUS_FILE_BASENAMES = new Set(["helper", "helpers", "util", "utils", "common"]);
+const KEBAB_CASE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function getFeatureSegments(relativePath) {
+  const normalizedPath = relativePath.split(path.sep).join("/");
+  return normalizedPath.split("/");
+}
+
+function createIssue(contract, ruleId, relativePath, message, options = {}) {
+  return createContractIssue(contract, {
+    ruleId,
+    category: "project-layout",
+    relativePath,
+    message,
+    verificationMode: options.verificationMode,
+    confidence: options.confidence,
+    evidence: options.evidence,
+    suggestion: options.suggestion,
+  });
+}
+
+function collectSharedConsumers(sourceFiles) {
+  const consumers = new Set();
+
+  for (const file of sourceFiles) {
+    if (!file.relativePath.startsWith("src/") || !file.featureName || file.featureName === "shared") {
+      continue;
+    }
+
+    for (const statement of file.ast.statements) {
+      if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+        continue;
+      }
+
+      const importedPath = resolveImportRelativePath(file.relativePath, statement.moduleSpecifier.text);
+      if (importedPath?.startsWith("src/shared/")) {
+        consumers.add(file.featureName);
+      }
+    }
+  }
+
+  return consumers;
+}
+
+function collectExportedTypeCount(file) {
+  let exportedTypeCount = 0;
+
+  for (const statement of file.ast.statements) {
+    if (
+      (ts.isTypeAliasDeclaration(statement) || ts.isInterfaceDeclaration(statement) || ts.isEnumDeclaration(statement)) &&
+      Array.isArray(statement.modifiers) &&
+      statement.modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+    ) {
+      exportedTypeCount += 1;
+    }
+  }
+
+  return exportedTypeCount;
+}
+
+export async function verifyProjectLayout(_targetPath, contract, analysisContext, options = {}) {
+  const activeRuleIds = getActiveVerifyRuleIds(contract);
+  const issues = [];
+  const files = analysisContext.sourceFiles.map((file) => file.relativePath);
+  const sharedConsumers = collectSharedConsumers(analysisContext.sourceFiles);
+  const featureEntrypoints = new Set(
+    files.filter((relativePath) => relativePath.startsWith("src/") && relativePath.endsWith("/index.ts")).map((relativePath) => relativePath.split("/")[1]),
+  );
+
+  for (const relativePath of files) {
+    const normalizedPath = relativePath.split(path.sep).join("/");
+    const segments = getFeatureSegments(relativePath);
+    const fileName = segments.at(-1);
+    const fileBaseName = fileName.replace(/\.ts$/, "");
+
+    if (
+      (normalizedPath.startsWith("src/") || normalizedPath.startsWith("test/")) &&
+      shouldRunRule(options.onlyRuleIds, "kebab-case-paths") &&
+      activeRuleIds.has("kebab-case-paths")
+    ) {
+      for (const segment of segments.slice(1)) {
+        const segmentBaseName = segment
+          .replace(/\.test\.ts$/, "")
+          .replace(/\.ts$/, "")
+          .replace(/\.[a-z]+$/, "");
+        if (!segmentBaseName || RESERVED_ROOT_SOURCE_FILES.has(segment) || RESERVED_FEATURE_FOLDERS.has(segmentBaseName)) {
+          continue;
+        }
+
+        if (!KEBAB_CASE_PATTERN.test(segmentBaseName)) {
+          issues.push(createIssue(contract, "kebab-case-paths", relativePath, `path segment must use kebab-case: ${segment}`));
+        }
+      }
+    }
+
+    if (
+      normalizedPath.startsWith("src/") &&
+      segments.length === 2 &&
+      !RESERVED_ROOT_SOURCE_FILES.has(fileName) &&
+      shouldRunRule(options.onlyRuleIds, "feature-first-layout") &&
+      activeRuleIds.has("feature-first-layout")
+    ) {
+      issues.push(
+        createIssue(
+          contract,
+          "feature-first-layout",
+          relativePath,
+          "src/ root should only keep entrypoints and shared scaffold files when feature folders exist",
+          {
+            verificationMode: "heuristic",
+            confidence: "medium",
+          },
+        ),
+      );
+    }
+
+    if (
+      normalizedPath.startsWith("src/") &&
+      segments.length >= 3 &&
+      shouldRunRule(options.onlyRuleIds, "ambiguous-feature-filenames") &&
+      activeRuleIds.has("ambiguous-feature-filenames")
+    ) {
+      const baseWithoutRole = fileBaseName.split(".")[0];
+      if (AMBIGUOUS_FILE_BASENAMES.has(baseWithoutRole)) {
+        issues.push(createIssue(contract, "ambiguous-feature-filenames", relativePath, `ambiguous feature filename is forbidden: ${fileName}`));
+      }
+    }
+
+    if (
+      normalizedPath.startsWith("test/") &&
+      shouldRunRule(options.onlyRuleIds, "test-file-naming") &&
+      activeRuleIds.has("test-file-naming") &&
+      !normalizedPath.endsWith(".test.ts")
+    ) {
+      issues.push(createIssue(contract, "test-file-naming", relativePath, "test files must use the .test.ts suffix"));
+    }
+  }
+
+  if (shouldRunRule(options.onlyRuleIds, "singular-feature-folders") && activeRuleIds.has("singular-feature-folders")) {
+    const featureFolders = new Set(
+      files
+        .filter((relativePath) => relativePath.startsWith("src/"))
+        .map((relativePath) => relativePath.split("/")[1])
+        .filter((segment) => segment && !RESERVED_FEATURE_FOLDERS.has(segment) && !segment.endsWith(".ts")),
+    );
+
+    for (const featureFolder of featureFolders) {
+      if (featureFolder.endsWith("s")) {
+        issues.push(createIssue(contract, "singular-feature-folders", `src/${featureFolder}`, `feature folders must be singular: ${featureFolder}`));
+      }
+    }
+  }
+
+  if (shouldRunRule(options.onlyRuleIds, "restricted-shared-boundaries") && activeRuleIds.has("restricted-shared-boundaries")) {
+    if (files.some((relativePath) => relativePath.startsWith("src/shared/")) && sharedConsumers.size < 2) {
+      issues.push(
+        createIssue(contract, "restricted-shared-boundaries", "src/shared", "src/shared should exist only when at least two features consume it", {
+          verificationMode: "heuristic",
+          confidence: "medium",
+          evidence: `${sharedConsumers.size} feature consumer(s) found`,
+        }),
+      );
+    }
+
+    if (files.some((relativePath) => relativePath.startsWith("src/app/"))) {
+      const hasCompositionSurface = files.some(
+        (relativePath) => relativePath.startsWith("src/app/") && /(runtime|bootstrap|compose|wiring|container|module|app)\./.test(relativePath),
+      );
+
+      if (!hasCompositionSurface) {
+        issues.push(
+          createIssue(contract, "restricted-shared-boundaries", "src/app", "src/app should be reserved for real composition and wiring concerns", {
+            verificationMode: "heuristic",
+            confidence: "medium",
+          }),
+        );
+      }
+    }
+  }
+
+  if (
+    (shouldRunRule(options.onlyRuleIds, "cross-feature-entrypoint-imports") && activeRuleIds.has("cross-feature-entrypoint-imports")) ||
+    (shouldRunRule(options.onlyRuleIds, "types-file-justification") && activeRuleIds.has("types-file-justification"))
+  ) {
+    for (const file of analysisContext.sourceFiles) {
+      if (!file.relativePath.startsWith("src/")) {
+        continue;
+      }
+
+      for (const statement of file.ast.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+          continue;
+        }
+
+        const importedRelativePath = resolveImportRelativePath(file.relativePath, statement.moduleSpecifier.text);
+        if (!importedRelativePath?.startsWith("src/")) {
+          continue;
+        }
+
+        const importedSegments = importedRelativePath.split("/");
+        const importedFeatureName = importedSegments[1];
+        const targetFileName = importedSegments.at(-1);
+
+        if (
+          shouldRunRule(options.onlyRuleIds, "cross-feature-entrypoint-imports") &&
+          activeRuleIds.has("cross-feature-entrypoint-imports") &&
+          file.featureName &&
+          importedFeatureName &&
+          file.featureName !== importedFeatureName &&
+          featureEntrypoints.has(importedFeatureName) &&
+          !RESERVED_FEATURE_FOLDERS.has(importedFeatureName) &&
+          !RESERVED_ROOT_SOURCE_FILES.has(targetFileName) &&
+          targetFileName !== "index.ts"
+        ) {
+          issues.push(
+            createIssue(
+              contract,
+              "cross-feature-entrypoint-imports",
+              file.relativePath,
+              `cross-feature import must go through ${importedFeatureName}/index.ts instead of ${importedRelativePath}`,
+            ),
+          );
+        }
+      }
+
+      if (
+        shouldRunRule(options.onlyRuleIds, "types-file-justification") &&
+        activeRuleIds.has("types-file-justification") &&
+        file.relativePath.endsWith(".types.ts")
+      ) {
+        const exportedTypeCount = collectExportedTypeCount(file);
+        const externalImportCount = analysisContext.sourceFiles.filter(
+          (candidate) => candidate.relativePath !== file.relativePath && candidate.raw.includes(`"${path.posix.basename(file.relativePath, ".ts")}.ts"`),
+        ).length;
+
+        if (exportedTypeCount <= 1 && externalImportCount === 0) {
+          issues.push(
+            createIssue(contract, "types-file-justification", file.relativePath, ".types.ts should be reserved for substantial shared feature types", {
+              verificationMode: "heuristic",
+              confidence: "medium",
+              evidence: `${exportedTypeCount} exported type(s), ${externalImportCount} external import(s)`,
+            }),
+          );
+        }
+      }
+    }
+  }
+
+  return issues;
+}