@yansirplus/cli 0.5.17

package/dist/check/algorithmic/projection-boundary-checks.mjs

@@ -0,0 +1,302 @@
+export const createProjectionBoundaryChecks = ({
+  fs,
+  path,
+  ts,
+  repoRoot,
+  read,
+  readJson,
+  walk,
+  isRecord,
+  failIfAny,
+  graphWorkspacePackageRecords,
+  sourceModuleGraph,
+  workspacePackageRecords,
+}) => {
+  const projectionFoldBoundaryPath = "architecture/projection-fold-boundary.json";
+
+  const hasExportModifier = (node) =>
+    ts.canHaveModifiers(node) &&
+    (ts.getModifiers(node) ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+
+  const addBindingNames = (name, names) => {
+    if (ts.isIdentifier(name)) {
+      names.add(name.text);
+      return;
+    }
+    if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) {
+      for (const element of name.elements) {
+        if (ts.isBindingElement(element)) addBindingNames(element.name, names);
+      }
+    }
+  };
+
+  const exportedSymbolNamesForFile = (file) => {
+    const names = new Set();
+    const sourceFile = ts.createSourceFile(
+      file,
+      read(file),
+      ts.ScriptTarget.Latest,
+      true,
+      file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    );
+    const visit = (node) => {
+      if (hasExportModifier(node)) {
+        if (
+          (ts.isFunctionDeclaration(node) ||
+            ts.isClassDeclaration(node) ||
+            ts.isInterfaceDeclaration(node) ||
+            ts.isTypeAliasDeclaration(node) ||
+            ts.isEnumDeclaration(node)) &&
+          node.name !== undefined
+        ) {
+          names.add(node.name.text);
+        }
+        if (ts.isVariableStatement(node)) {
+          for (const declaration of node.declarationList.declarations) {
+            addBindingNames(declaration.name, names);
+          }
+        }
+      }
+      if (
+        ts.isExportDeclaration(node) &&
+        node.exportClause !== undefined &&
+        ts.isNamedExports(node.exportClause)
+      ) {
+        for (const element of node.exportClause.elements) names.add(element.name.text);
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return names;
+  };
+
+  const exportedSymbolNamesUnder = (relativePath) => {
+    const names = new Set();
+    for (const file of walk(relativePath).filter((entry) => /\.(?:ts|tsx|mts|cts)$/u.test(entry))) {
+      for (const name of exportedSymbolNamesForFile(file)) names.add(name);
+    }
+    return names;
+  };
+
+  const projectionFoldBoundaryFailures = () => {
+    const failures = [];
+    if (!fs.existsSync(path.join(repoRoot, projectionFoldBoundaryPath))) {
+      failures.push(`${projectionFoldBoundaryPath}: missing projection fold audit decision`);
+      return failures;
+    }
+
+    const registry = readJson(projectionFoldBoundaryPath);
+    if (registry.schemaVersion !== 1) {
+      failures.push(`${projectionFoldBoundaryPath}: schemaVersion must be 1`);
+    }
+    if (registry.decision !== "keep-consumer-boundary") {
+      failures.push(
+        `${projectionFoldBoundaryPath}: decision must stay keep-consumer-boundary until a shared core fold source exists`,
+      );
+    }
+    if (registry.sharedFold !== false) {
+      failures.push(`${projectionFoldBoundaryPath}: sharedFold must be false for this decision`);
+    }
+    for (const key of ["blockingContractReason", "corePromotionCondition"]) {
+      if (typeof registry[key] !== "string" || registry[key].trim().length === 0) {
+        failures.push(`${projectionFoldBoundaryPath}: ${key} must record the audit contract`);
+      }
+    }
+
+    const packagePathByName = new Map(
+      workspacePackageRecords().map((record) => [record.name, record.path]),
+    );
+    const records = graphWorkspacePackageRecords(repoRoot).filter(
+      (record) => typeof record.name === "string" && record.name.startsWith("@agent-os/"),
+    );
+    const graph = sourceModuleGraph(repoRoot, records);
+    const ownedFolds = Array.isArray(registry.ownedFolds) ? registry.ownedFolds : [];
+    if (ownedFolds.length === 0) {
+      failures.push(`${projectionFoldBoundaryPath}: ownedFolds must be non-empty`);
+    }
+    for (const [index, fold] of ownedFolds.entries()) {
+      const label =
+        isRecord(fold) && typeof fold.id === "string" ? fold.id : `ownedFolds[${index}]`;
+      if (!isRecord(fold)) {
+        failures.push(`${projectionFoldBoundaryPath}:${label}: fold entry must be an object`);
+        continue;
+      }
+      const packageName = fold.packageName;
+      const file = fold.file;
+      const exports = Array.isArray(fold.exports) ? fold.exports : [];
+      if (typeof packageName !== "string" || !packageName.startsWith("@agent-os/")) {
+        failures.push(`${projectionFoldBoundaryPath}:${label}: packageName must be @agent-os/*`);
+        continue;
+      }
+      const packagePath = packagePathByName.get(packageName);
+      if (typeof packagePath !== "string") {
+        failures.push(`${projectionFoldBoundaryPath}:${label}: package ${packageName} is missing`);
+        continue;
+      }
+      if (typeof file !== "string" || !file.startsWith(`${packagePath}/`)) {
+        failures.push(
+          `${projectionFoldBoundaryPath}:${label}: file must live under package ${packageName}`,
+        );
+        continue;
+      }
+      if (!fs.existsSync(path.join(repoRoot, file))) {
+        failures.push(`${projectionFoldBoundaryPath}:${label}: file is missing: ${file}`);
+        continue;
+      }
+      if (exports.length === 0 || exports.some((name) => typeof name !== "string")) {
+        failures.push(`${projectionFoldBoundaryPath}:${label}: exports must be non-empty strings`);
+        continue;
+      }
+      const actualExports = exportedSymbolNamesForFile(file);
+      for (const name of exports) {
+        if (!actualExports.has(name)) {
+          failures.push(`${file}: projection-fold-boundary:${label}: missing export ${name}`);
+        }
+      }
+      if (
+        !Array.isArray(fold.consumerRoots) ||
+        fold.consumerRoots.length === 0 ||
+        fold.consumerRoots.some((root) => typeof root !== "string")
+      ) {
+        failures.push(
+          `${projectionFoldBoundaryPath}:${label}: consumerRoots must name the true consumer set`,
+        );
+      }
+      if (
+        !Array.isArray(fold.allowedConsumers) ||
+        fold.allowedConsumers.some((consumer) => typeof consumer !== "string")
+      ) {
+        failures.push(`${projectionFoldBoundaryPath}:${label}: allowedConsumers must be strings`);
+        continue;
+      }
+      const allowedConsumers = new Set(fold.allowedConsumers);
+      for (const consumer of allowedConsumers) {
+        if (!fs.existsSync(path.join(repoRoot, consumer))) {
+          failures.push(
+            `${projectionFoldBoundaryPath}:${label}: consumer file is missing ${String(consumer)}`,
+          );
+        }
+      }
+      const incoming = graph.edges.filter((edge) => edge.toFile === file && edge.fromFile !== file);
+      const actualConsumers = new Set(incoming.map((edge) => edge.fromFile));
+      for (const edge of incoming) {
+        if (!allowedConsumers.has(edge.fromFile)) {
+          failures.push(
+            `${edge.fromFile}:${edge.line}:${edge.column}: projection-fold-boundary:${label}: unexpected consumer of ${file} via ${edge.specifier}`,
+          );
+        }
+      }
+      for (const consumer of allowedConsumers) {
+        if (!actualConsumers.has(consumer)) {
+          failures.push(
+            `${projectionFoldBoundaryPath}:${label}: declared consumer ${String(consumer)} does not import ${file}`,
+          );
+        }
+      }
+    }
+
+    const forbiddenCoreExports = Array.isArray(registry.coreForbiddenExports)
+      ? registry.coreForbiddenExports
+      : [];
+    if (
+      forbiddenCoreExports.length === 0 ||
+      forbiddenCoreExports.some((name) => typeof name !== "string")
+    ) {
+      failures.push(
+        `${projectionFoldBoundaryPath}: coreForbiddenExports must be non-empty strings`,
+      );
+    } else {
+      const coreExports = exportedSymbolNamesUnder("packages/core/src");
+      for (const name of forbiddenCoreExports) {
+        if (coreExports.has(name)) {
+          failures.push(
+            `packages/core/src: projection-fold-boundary: core must not export disputed event fold symbol ${name}`,
+          );
+        }
+      }
+    }
+
+    return failures;
+  };
+
+  const checkProjectionFoldBoundary = () => {
+    const failures = projectionFoldBoundaryFailures();
+    failIfAny("projection fold boundary", failures);
+  };
+
+  const checkLimitRegistry = () => {
+    const failures = [];
+    if (!fs.existsSync(path.join(repoRoot, "docs/limits.json"))) {
+      failures.push("docs/limits.json is missing");
+      failIfAny("limit registry", failures);
+      return;
+    }
+    const registry = readJson("docs/limits.json");
+    const allowedClasses = new Set(["contract", "policy", "closed"]);
+    if (!Number.isInteger(registry.version) || registry.version <= 0) {
+      failures.push("docs/limits.json version must be a positive integer");
+    }
+    if (!Array.isArray(registry.limits) || registry.limits.length === 0) {
+      failures.push("docs/limits.json limits must be a non-empty array");
+      failIfAny("limit registry", failures);
+      return;
+    }
+    const seen = new Set();
+    for (const [index, limit] of registry.limits.entries()) {
+      const label = isRecord(limit) && typeof limit.id === "string" ? limit.id : `limits[${index}]`;
+      if (!isRecord(limit)) {
+        failures.push(`${label}: expected object`);
+        continue;
+      }
+      if (!/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/u.test(limit.id ?? "")) {
+        failures.push(`${label}.id: expected stable lowercase dotted identifier`);
+      }
+      if (seen.has(limit.id)) failures.push(`${label}.id: duplicate ${limit.id}`);
+      seen.add(limit.id);
+      if (!allowedClasses.has(limit.class))
+        failures.push(`${label}.class: expected contract, policy, or closed`);
+      for (const field of ["owner", "value", "reason"]) {
+        if (typeof limit[field] !== "string" || limit[field].trim().length === 0) {
+          failures.push(`${label}.${field}: required`);
+        }
+      }
+      if (!Array.isArray(limit.sourcePaths) || limit.sourcePaths.length === 0) {
+        failures.push(`${label}.sourcePaths: non-empty array required`);
+      } else {
+        for (const sourcePath of limit.sourcePaths) {
+          const file = String(sourcePath).split("#", 1)[0];
+          if (
+            path.isAbsolute(file) ||
+            file.includes("..") ||
+            !fs.existsSync(path.join(repoRoot, file))
+          ) {
+            failures.push(`${label}.sourcePaths: ${sourcePath} does not point to a repo file`);
+          }
+        }
+      }
+      if (
+        limit.class === "policy" &&
+        (typeof limit.overrideSurface !== "string" || limit.overrideSurface.trim().length === 0)
+      ) {
+        failures.push(
+          `${label}.overrideSurface: policy limits require an ordinary override surface`,
+        );
+      }
+      if (
+        (limit.class === "contract" || limit.class === "closed") &&
+        limit.overrideSurface !== undefined
+      ) {
+        failures.push(
+          `${label}.overrideSurface: ${limit.class} limits must not expose ordinary overrides`,
+        );
+      }
+    }
+    failIfAny("limit registry", failures);
+  };
+
+  return {
+    projectionFoldBoundaryFailures,
+    checkProjectionFoldBoundary,
+    checkLimitRegistry,
+  };
+};

package/dist/check/algorithmic/repo-surface-checks.mjs

@@ -0,0 +1,267 @@
+export const createRepoSurfaceChecks = ({
+  fs,
+  path,
+  ts,
+  repoRoot,
+  read,
+  readJson,
+  walk,
+  compare,
+  isRecord,
+  failIfAny,
+  collectAgentDocsModel,
+  apiSourceMode,
+  exportedNamesForPackage,
+  sourceTsdocApiMarkdown,
+  sourceTsdocModes,
+  sourceTsdocRecordsForPackage,
+  validateSourceTsdocRecords,
+}) => {
+  const manifestEntries = (file, section) => {
+    const source = fs.readFileSync(file, "utf8");
+    const start = source.indexOf(`## ${section}`);
+    if (start === -1) return [];
+    const rest = source.slice(start + section.length + 3);
+    const next = rest.search(/^## /mu);
+    const body = next === -1 ? rest : rest.slice(0, next);
+    return [...body.matchAll(/`([^`:]+):([^`]+)`/gu)].map((match) => ({
+      name: match[0].slice(1, -1),
+      section,
+      line: source.slice(0, start + section.length + 3 + match.index).split("\n").length,
+    }));
+  };
+
+  const manifestNames = (file, section) =>
+    new Set(manifestEntries(file, section).map((entry) => entry.name));
+
+  const duplicateManifestEntries = (file, sections) => {
+    const entries = sections.flatMap((section) => manifestEntries(file, section));
+    const byName = new Map();
+    for (const entry of entries) {
+      byName.set(entry.name, [...(byName.get(entry.name) ?? []), entry]);
+    }
+    return [...byName.entries()]
+      .filter(([, occurrences]) => occurrences.length > 1)
+      .map(([name, occurrences]) => ({ name, occurrences }));
+  };
+
+  const targetPackages = () => {
+    const surface = readJson("docs/surface.json");
+    return surface.packages.filter((pkg) => {
+      const packageJson = path.join(repoRoot, pkg.path, "package.json");
+      if (!fs.existsSync(packageJson)) return false;
+      const manifest = JSON.parse(fs.readFileSync(packageJson, "utf8"));
+      return (
+        pkg.apiSource !== undefined || (pkg.published === true && manifest.exports !== undefined)
+      );
+    });
+  };
+
+  const checkPublicApi = () => {
+    const failures = [];
+    for (const target of targetPackages()) {
+      if (target.apiSource === undefined) {
+        failures.push(
+          `${target.name}: published package exports require apiSource in docs/surface.json`,
+        );
+        continue;
+      }
+      const manifest = path.join(repoRoot, target.apiSource);
+      if (!fs.existsSync(manifest)) {
+        failures.push(`missing public API intent source for ${target.name}: ${target.apiSource}`);
+        continue;
+      }
+
+      const mode = apiSourceMode(target);
+      if (sourceTsdocModes.has(mode)) {
+        const records = sourceTsdocRecordsForPackage(repoRoot, target);
+        failures.push(...validateSourceTsdocRecords(target, records));
+        const expected = `${sourceTsdocApiMarkdown(target, records).replace(/\s+$/u, "")}\n`;
+        if (fs.readFileSync(manifest, "utf8") !== expected) {
+          failures.push(`${target.apiSource} is stale; run bun run docs:generate`);
+        }
+      } else if (mode !== "manual") {
+        failures.push(`${target.name}: unsupported apiSourceMode ${mode}`);
+      }
+
+      const publicSections = ["Public exports", "Experimental exports", "Deprecated exports"];
+      for (const duplicate of duplicateManifestEntries(manifest, [
+        ...publicSections,
+        "Internal-only exports",
+      ])) {
+        const refs = duplicate.occurrences
+          .map((entry) => `${entry.section}:${entry.line}`)
+          .join(", ");
+        failures.push(
+          `${target.name}: ${target.apiSource} declares duplicate API entry ${duplicate.name} at ${refs}`,
+        );
+      }
+
+      const declaredPublic = new Set(
+        publicSections.flatMap((section) => [...manifestNames(manifest, section)]),
+      );
+      const internal = manifestNames(manifest, "Internal-only exports");
+      const actual = exportedNamesForPackage(repoRoot, target)
+        .map((record) => record.key)
+        .sort();
+
+      for (const name of actual) {
+        if (!declaredPublic.has(name)) {
+          failures.push(
+            `${target.name}: exported but not declared in ${target.apiSource}: ${name}`,
+          );
+        }
+        if (internal.has(name)) {
+          failures.push(`${target.name}: internal export is still exported: ${name}`);
+        }
+      }
+      for (const name of declaredPublic) {
+        if (!actual.includes(String(name))) {
+          failures.push(
+            `${target.name}: ${target.apiSource} lists missing export: ${String(name)}`,
+          );
+        }
+      }
+    }
+    failIfAny("public API projection", failures);
+  };
+
+  const checkEventNamespaces = () => {
+    const failures = collectAgentDocsModel(repoRoot).namespaceModel.failures;
+    failIfAny("event namespace projection", failures);
+  };
+
+  const importSpecifiers = (content) => {
+    const sourceFile = ts.createSourceFile(
+      "agentos-check.mjs",
+      content,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.JS,
+    );
+    const specifiers = [];
+    const visit = (node) => {
+      if (
+        (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+        node.moduleSpecifier !== undefined &&
+        ts.isStringLiteralLike(node.moduleSpecifier)
+      ) {
+        specifiers.push(node.moduleSpecifier.text);
+      }
+      if (
+        ts.isCallExpression(node) &&
+        node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+        node.arguments.length === 1 &&
+        ts.isStringLiteralLike(node.arguments[0])
+      ) {
+        specifiers.push(node.arguments[0].text);
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return specifiers;
+  };
+
+  const ruleConstraints = (ruleId) => {
+    const source = readJson("docs/agent/boundary-rules.source.json");
+    const rule = source.rules?.find((entry) => isRecord(entry) && entry.id === ruleId);
+    if (!isRecord(rule) || !isRecord(rule.constraints)) {
+      throw new Error(`docs/agent/boundary-rules.source.json: ${ruleId} missing constraints`);
+    }
+    return rule.constraints;
+  };
+
+  const checkRepoToolingSurface = () => {
+    const constraints = ruleConstraints("repo-tooling-surface");
+    const failures = [];
+    const expected = [...constraints.rootScripts].sort(compare);
+    const actual = Object.keys(readJson("package.json").scripts ?? {}).sort(compare);
+    for (const scriptName of expected.filter((name) => !actual.includes(name))) {
+      failures.push(`package.json: missing root script ${scriptName}`);
+    }
+    for (const scriptName of actual.filter((name) => !expected.includes(name))) {
+      failures.push(`package.json: unexpected root script ${scriptName}`);
+    }
+    for (const scriptName of actual) {
+      if (
+        /^(check|test):/u.test(scriptName) &&
+        !constraints.allowedPrefixedRootScripts.includes(scriptName)
+      ) {
+        failures.push(`package.json: unexpected fine-grained root script ${scriptName}`);
+      }
+    }
+
+    for (const file of walk("scripts")) {
+      if (!constraints.scriptsDirectoryAllowPrefixes.some((prefix) => file.startsWith(prefix))) {
+        failures.push(`scripts/: non-parallel-dev script remains at ${file}`);
+        continue;
+      }
+      if (!constraints.scriptsDirectoryAllowedExtensions.includes(path.extname(file))) {
+        failures.push(`scripts/: ${file} must use an allowed script extension`);
+      }
+    }
+
+    const packagesRoot = path.join(repoRoot, "packages");
+    const cliRoot = path.join(packagesRoot, "cli");
+    const cliManifest = readJson("packages/cli/package.json");
+    const declaredCliPackageDependencies = new Set(
+      ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"].flatMap(
+        (section) => Object.keys(cliManifest[section] ?? {}),
+      ),
+    );
+    const packageSpecPrefixesRequiringDeclaredDependency =
+      constraints.packageSpecPrefixesRequireDeclaredDependency ??
+      constraints.forbiddenPackageSpecPrefixes ??
+      [];
+    const declaredPackageForSpecifier = (specifier) =>
+      [...declaredCliPackageDependencies].find(
+        (name) => specifier === name || specifier.startsWith(`${name}/`),
+      );
+    for (const file of walk("packages/cli/src").filter((entry) =>
+      /\.(?:mjs|js|ts|tsx)$/u.test(entry),
+    )) {
+      const content = read(file);
+      for (const specifier of importSpecifiers(content)) {
+        if (
+          packageSpecPrefixesRequiringDeclaredDependency.some((prefix) =>
+            specifier.startsWith(prefix),
+          ) &&
+          declaredPackageForSpecifier(specifier) === undefined
+        ) {
+          failures.push(`${file}: CLI package specifier ${specifier} is not a declared dependency`);
+        }
+        if (specifier.startsWith(".")) {
+          const resolved = path.resolve(path.dirname(path.join(repoRoot, file)), specifier);
+          const isPackagesSource =
+            resolved === packagesRoot || resolved.startsWith(`${packagesRoot}${path.sep}`);
+          const isCliSource = resolved === cliRoot || resolved.startsWith(`${cliRoot}${path.sep}`);
+          if (isPackagesSource && !isCliSource) {
+            failures.push(`${file}: CLI must not import packages source via ${specifier}`);
+          }
+        }
+      }
+    }
+
+    const legacyPattern = new RegExp(constraints.forbiddenLegacyScriptReferencePattern, "u");
+    for (const file of constraints.legacyReferenceScanRoots.flatMap((root) => walk(root))) {
+      if (!/\.(?:json|jsonc|md|mjs|ts|tsx)$/u.test(file)) continue;
+      for (const [index, line] of read(file).split("\n").entries()) {
+        if (legacyPattern.test(line)) {
+          failures.push(`${file}:${index + 1}: legacy scripts/ check/generate reference remains`);
+        }
+      }
+    }
+    failIfAny("repo tooling surface", failures);
+  };
+
+  return {
+    manifestEntries,
+    manifestNames,
+    duplicateManifestEntries,
+    importSpecifiers,
+    ruleConstraints,
+    checkPublicApi,
+    checkEventNamespaces,
+    checkRepoToolingSurface,
+  };
+};