@opensip-cli/checks-universal 0.1.0

package/dist/checks/documentation/_public-api-graph.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Public-API reachability graph for the public-api-jsdoc check.
+ *
+ * Computes the set of source files reachable from a package's
+ * `package.json#exports` entry barrels via `export ... from` re-exports.
+ *
+ * Why re-exports only (not plain `import`): a file imported by a public
+ * file is internal to that file — its exports are not part of the
+ * package's published surface. Only `export ... from './foo.js'`
+ * re-makes `./foo.ts`'s exports visible to consumers.
+ *
+ * Used by `public-api-jsdoc` to scope JSDoc requirements to the actual
+ * npm-published API surface, not every `export` in every internal file.
+ */
+/**
+ * Reset all memoized state. Intended for tests.
+ */
+export declare function _resetPublicApiGraphCache(): void;
+/**
+ * Determine whether `filePath` is part of the package's public API
+ * surface — i.e., reachable from the package's `exports` entries via
+ * `export ... from` re-export chains.
+ *
+ * Returns `true` if reachable; `false` if not. Returns `true` (open
+ * fail) when the package surface cannot be determined (no
+ * package.json, no `exports`, etc.) so the check degrades to its
+ * historical broad behavior rather than silently passing.
+ */
+export declare function isInPublicApiSurface(filePath: string): boolean;
+//# sourceMappingURL=_public-api-graph.d.ts.map

package/dist/checks/documentation/_public-api-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_public-api-graph.d.ts","sourceRoot":"","sources":["../../../src/checks/documentation/_public-api-graph.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;GAaG;AA8BH;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAqBD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI9D"}

package/dist/checks/documentation/_public-api-graph.js

@@ -0,0 +1,304 @@
+// @fitness-ignore-file unbounded-memory -- reads small text files (package.json, src/index.ts barrels) for public-API surface computation; per-file memory bounded by standard config/barrel shape.
+/**
+ * @fileoverview Public-API reachability graph for the public-api-jsdoc check.
+ *
+ * Computes the set of source files reachable from a package's
+ * `package.json#exports` entry barrels via `export ... from` re-exports.
+ *
+ * Why re-exports only (not plain `import`): a file imported by a public
+ * file is internal to that file — its exports are not part of the
+ * package's published surface. Only `export ... from './foo.js'`
+ * re-makes `./foo.ts`'s exports visible to consumers.
+ *
+ * Used by `public-api-jsdoc` to scope JSDoc requirements to the actual
+ * npm-published API surface, not every `export` in every internal file.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+const surfaceCache = new Map();
+// Match `export { x }` / `export type { x }` / `export *` /
+// `export * as ns` followed by `from '...'`. Split into two simpler
+// alternatives to keep regex-complexity below the lint threshold and
+// avoid catastrophic backtracking on pathological `{...}` blocks.
+// Both patterns are anchored to line boundaries (gm) and use bounded
+// character classes — no nested quantifiers — so they run in linear
+// time over input.
+/* eslint-disable sonarjs/slow-regex -- both patterns are linear: anchored to line start with `^` under the gm flag, and use negated character classes (`[^}\n]*`, `[^'"]+`) rather than nested quantifiers, so they cannot backtrack catastrophically */
+const RE_EXPORT_NAMED_FROM = /^\s*export\s+(?:type\s+)?\{[^}\n]*\}\s+from\s+['"]([^'"]+)['"]/gm;
+const RE_EXPORT_STAR_FROM = /^\s*export\s+\*(?:\s+as\s+\w+)?\s+from\s+['"]([^'"]+)['"]/gm;
+/* eslint-enable sonarjs/slow-regex */
+/**
+ * Reset all memoized state. Intended for tests.
+ */
+export function _resetPublicApiGraphCache() {
+    surfaceCache.clear();
+}
+/**
+ * Walk upward from `filePath` to find the nearest `package.json`.
+ * Returns the package root directory (the directory containing
+ * `package.json`), or `undefined` if none found before the filesystem
+ * root.
+ */
+function findPackageRoot(filePath) {
+    let dir = dirname(filePath);
+    // Bound the walk to avoid pathological loops on weird mounts.
+    for (let i = 0; i < 64; i++) {
+        const candidate = join(dir, 'package.json');
+        if (existsSync(candidate))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Determine whether `filePath` is part of the package's public API
+ * surface — i.e., reachable from the package's `exports` entries via
+ * `export ... from` re-export chains.
+ *
+ * Returns `true` if reachable; `false` if not. Returns `true` (open
+ * fail) when the package surface cannot be determined (no
+ * package.json, no `exports`, etc.) so the check degrades to its
+ * historical broad behavior rather than silently passing.
+ */
+export function isInPublicApiSurface(filePath) {
+    const surface = getPackagePublicSurface(filePath);
+    if (!surface)
+        return true;
+    return surface.publicFiles.has(filePath);
+}
+/**
+ * Compute (and memoize) the public-API surface for the package
+ * containing `filePath`.
+ */
+function getPackagePublicSurface(filePath) {
+    const packageRoot = findPackageRoot(filePath);
+    if (!packageRoot)
+        return null;
+    const cached = surfaceCache.get(packageRoot);
+    if (cached !== undefined)
+        return cached;
+    const surface = computePackagePublicSurface(packageRoot);
+    surfaceCache.set(packageRoot, surface);
+    return surface;
+}
+function computePackagePublicSurface(packageRoot) {
+    const pkg = readPackageJson(join(packageRoot, 'package.json'));
+    if (!pkg)
+        return null;
+    if (isBinaryOnlyPackage(pkg)) {
+        return { packageRoot, publicFiles: new Set() };
+    }
+    const entryPaths = collectExportEntries(pkg, packageRoot);
+    if (entryPaths.length === 0)
+        return null;
+    const publicFiles = seedPublicFiles(entryPaths, packageRoot);
+    walkReExportGraph(publicFiles);
+    return { packageRoot, publicFiles };
+}
+/**
+ * Read and parse a `package.json` file. Returns `null` if the file
+ * cannot be read or does not contain a JSON object.
+ */
+function readPackageJson(pkgJsonPath) {
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+    }
+    catch {
+        // @fitness-ignore-next-line error-handling-quality -- malformed/unreadable package.json deliberately surfaces via null return; caller treats absence as "no public-API surface info available" and falls back to broad scanning.
+        return null;
+    }
+    if (typeof pkg !== 'object' || pkg === null)
+        return null;
+    return pkg;
+}
+/**
+ * A binary-only package (CLI executable with no library exports) has
+ * no public API surface at all — every source file is internal. The
+ * caller treats this as "empty public surface" rather than "unknown
+ * surface" so the check correctly skips every file in the package.
+ */
+function isBinaryOnlyPackage(pkg) {
+    return (pkg.exports === undefined &&
+        pkg.main === undefined &&
+        pkg.module === undefined &&
+        pkg.bin !== undefined);
+}
+/**
+ * Map each package.json entry to a source file path and return the
+ * initial set seeded for the re-export BFS walk.
+ */
+function seedPublicFiles(entryPaths, packageRoot) {
+    const publicFiles = new Set();
+    for (const entry of entryPaths) {
+        const sourceFile = mapDistToSource(entry, packageRoot);
+        if (sourceFile)
+            publicFiles.add(sourceFile);
+    }
+    return publicFiles;
+}
+/**
+ * BFS the `export ... from` re-export graph starting from the seeded
+ * `publicFiles` set, adding every reached file to the same set.
+ */
+function walkReExportGraph(publicFiles) {
+    const queue = [...publicFiles];
+    while (queue.length > 0) {
+        const file = queue.shift();
+        /* v8 ignore next -- queue.shift() returns undefined only when empty, which the while condition prevents */
+        if (file === undefined)
+            continue;
+        let content;
+        try {
+            content = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        enqueueLocalReExports(content, dirname(file), publicFiles, queue);
+    }
+}
+/**
+ * Scan a file's content for relative `export ... from` re-exports and
+ * push any newly-discovered files into both `publicFiles` and `queue`.
+ */
+function enqueueLocalReExports(content, fileDir, publicFiles, queue) {
+    for (const regex of [RE_EXPORT_NAMED_FROM, RE_EXPORT_STAR_FROM]) {
+        for (const match of content.matchAll(regex)) {
+            const spec = match[1];
+            // Only follow relative imports — bare-package re-exports cross
+            // the package boundary and are out of scope for this package's
+            // surface.
+            if (!spec?.startsWith('.'))
+                continue;
+            const resolved = resolveLocalSpecifier(fileDir, spec);
+            if (resolved !== undefined && !publicFiles.has(resolved)) {
+                publicFiles.add(resolved);
+                queue.push(resolved);
+            }
+        }
+    }
+}
+/**
+ * Extract a flat list of file targets from a package.json `exports`
+ * field. Handles string, conditional, and subpath patterns. Patterns
+ * with `*` are not expanded — they are skipped (and the file falls
+ * through to the "no entries → open fail" path if no concrete entries
+ * remain).
+ *
+ * Falls back to `main` / `module` when `exports` is absent.
+ */
+function collectExportEntries(pkg, packageRoot) {
+    const out = [];
+    const exports_ = pkg.exports;
+    if (exports_ === undefined) {
+        for (const field of ['module', 'main']) {
+            const v = pkg[field];
+            if (typeof v === 'string')
+                out.push(resolveExportTarget(v, packageRoot));
+        }
+    }
+    else {
+        collectFromExportNode(exports_, packageRoot, out);
+    }
+    return out;
+}
+function collectFromExportNode(node, packageRoot, out) {
+    if (typeof node === 'string') {
+        // Skip wildcard patterns — we can't enumerate them without a
+        // directory scan, and conservatively treating the whole tree as
+        // public would re-introduce the false-positive flood.
+        if (node.includes('*'))
+            return;
+        out.push(resolveExportTarget(node, packageRoot));
+        return;
+    }
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectFromExportNode(item, packageRoot, out);
+        return;
+    }
+    if (typeof node === 'object' && node !== null) {
+        for (const value of Object.values(node)) {
+            collectFromExportNode(value, packageRoot, out);
+        }
+    }
+}
+function resolveExportTarget(target, packageRoot) {
+    const trimmed = target.startsWith('./') ? target.slice(2) : target;
+    return resolve(packageRoot, trimmed);
+}
+/**
+ * Map a built artifact path (typically `./dist/foo.js`) back to its
+ * TypeScript source path (typically `./src/foo.ts`). Returns
+ * `undefined` if no source file can be located.
+ *
+ * Honors common build layouts: `dist/` → `src/`, `dist/esm/` → `src/`,
+ * `build/` → `src/`. Also passes through already-source paths.
+ */
+function mapDistToSource(absPath, packageRoot) {
+    const rel = absPath.startsWith(packageRoot + sep)
+        ? absPath.slice(packageRoot.length + 1)
+        : absPath;
+    const candidates = [];
+    // dist/foo.js → src/foo.ts (and .tsx)
+    const distMatch = /^(dist|build)([\\/].*)?$/.exec(rel);
+    if (distMatch) {
+        const remainder = rel.slice(distMatch[1].length);
+        const inSrc = 'src' + remainder;
+        candidates.push(inSrc);
+    }
+    else {
+        candidates.push(rel);
+    }
+    for (const cand of candidates) {
+        const abs = isAbsolute(cand) ? cand : join(packageRoot, cand);
+        for (const ext of ['.ts', '.tsx', '.mts', '.cts']) {
+            const swapped = abs.replace(/\.(js|mjs|cjs)$/, ext);
+            if (swapped !== abs && fileExists(swapped))
+                return swapped;
+        }
+        if (fileExists(abs))
+            return abs;
+    }
+    return undefined;
+}
+/**
+ * Resolve a relative module specifier to an absolute source file path.
+ * Tries the literal target plus common extension swaps (`.js` → `.ts`,
+ * `.js` → `.tsx`), and `index.ts` fallback for directory imports.
+ */
+function resolveLocalSpecifier(fromDir, spec) {
+    const base = resolve(fromDir, spec);
+    const tries = [];
+    // Direct extension swap (the Node16 ESM `.js` import convention).
+    if (/\.(js|mjs|cjs)$/.test(base)) {
+        for (const ext of ['.ts', '.tsx', '.mts', '.cts']) {
+            tries.push(base.replace(/\.(js|mjs|cjs)$/, ext));
+        }
+    }
+    tries.push(base);
+    for (const ext of ['.ts', '.tsx', '.mts', '.cts'])
+        tries.push(base + ext);
+    // Directory imports (`./foo` → `./foo/index.ts`)
+    for (const ext of ['.ts', '.tsx', '.mts', '.cts'])
+        tries.push(join(base, 'index' + ext));
+    for (const candidate of tries) {
+        if (fileExists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function fileExists(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        // @fitness-ignore-next-line error-handling-quality -- filesystem probe; exception → false is the function's contract (missing path or permission denied means "not a file", same as truly absent).
+        return false;
+    }
+}
+//# sourceMappingURL=_public-api-graph.js.map

package/dist/checks/documentation/_public-api-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_public-api-graph.js","sourceRoot":"","sources":["../../../src/checks/documentation/_public-api-graph.ts"],"names":[],"mappings":"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"}

package/dist/checks/documentation/directive-audit.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Directive Audit — surfaces suppression directives for periodic review.
+ *
+ * Audits all suppression directives in the codebase for periodic review:
+ * - TypeScript: `@ts-expect-error`
+ * - ESLint: `eslint-disable`, `eslint-disable-next-line`, `eslint-disable-line`
+ * - Fitness: `@fitness-ignore-file`, `@fitness-ignore-next-line`
+ * - Graph: `@graph-ignore-file`, `@graph-ignore-next-line`
+ * - Semgrep: `nosemgrep`
+ *
+ * The four grammar parsers live in `./_directives/`. This file is
+ * purely the orchestration layer: filter files, dispatch to parsers,
+ * map directives onto CheckViolations.
+ */
+/**
+ * Check: documentation/directive-audit
+ *
+ * Audits all suppression directives (TypeScript, ESLint, fitness-ignore,
+ * semgrep) in the codebase for periodic review. This is an
+ * informational check that surfaces directives as warnings for audit
+ * purposes.
+ *
+ * Run via: `pnpm sip fit --check directive-audit`
+ */
+export declare const directiveAudit: import("@opensip-cli/fitness").Check;
+//# sourceMappingURL=directive-audit.d.ts.map

package/dist/checks/documentation/directive-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive-audit.d.ts","sourceRoot":"","sources":["../../../src/checks/documentation/directive-audit.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAmHH;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,sCA2BzB,CAAC"}

package/dist/checks/documentation/directive-audit.js

@@ -0,0 +1,144 @@
+// @fitness-ignore-file toctou-race-condition -- TOCTOU acceptable in this non-concurrent context
+// @fitness-ignore-file semgrep-justifications -- References nosemgrep patterns for directive parsing
+/**
+ * @fileoverview Directive Audit — surfaces suppression directives for periodic review.
+ *
+ * Audits all suppression directives in the codebase for periodic review:
+ * - TypeScript: `@ts-expect-error`
+ * - ESLint: `eslint-disable`, `eslint-disable-next-line`, `eslint-disable-line`
+ * - Fitness: `@fitness-ignore-file`, `@fitness-ignore-next-line`
+ * - Graph: `@graph-ignore-file`, `@graph-ignore-next-line`
+ * - Semgrep: `nosemgrep`
+ *
+ * The four grammar parsers live in `./_directives/`. This file is
+ * purely the orchestration layer: filter files, dispatch to parsers,
+ * map directives onto CheckViolations.
+ */
+import { defineCheck } from '@opensip-cli/fitness';
+import { parseESLintDirectives } from './_directives/eslint.js';
+import { parseFitnessDirectives } from './_directives/fitness.js';
+import { parseGraphDirectives } from './_directives/graph.js';
+import { parseSemgrepDirectives } from './_directives/semgrep.js';
+import { parseTypeScriptDirectives } from './_directives/typescript.js';
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+// Quick check markers — if none match, skip detailed parsing.
+const DIRECTIVE_MARKERS = [
+    '@ts-expect-error',
+    'eslint-disable',
+    '@fitness-ignore',
+    '@graph-ignore',
+    'nosemgrep',
+];
+// =============================================================================
+// HELPERS
+// =============================================================================
+function hasDirectiveMarkers(content) {
+    return DIRECTIVE_MARKERS.some((marker) => content.includes(marker));
+}
+function collectFileDirectives(content, filePath, file) {
+    const directives = [
+        ...parseTypeScriptDirectives(content, filePath, file),
+        ...parseESLintDirectives(content, filePath, file),
+        ...parseFitnessDirectives(content, filePath, file),
+        ...parseGraphDirectives(content, filePath, file),
+        ...parseSemgrepDirectives(content, filePath, file),
+    ];
+    directives.sort((a, b) => a.line - b.line);
+    return directives;
+}
+function isTypeScriptFile(filePath) {
+    return filePath.endsWith('.ts') || filePath.endsWith('.tsx');
+}
+function getFileName(filePath) {
+    const lastSlash = filePath.lastIndexOf('/');
+    return lastSlash === -1 ? filePath : filePath.slice(lastSlash + 1);
+}
+function directiveToViolation(directive) {
+    const reasonPart = directive.reason ? ` -- ${directive.reason}` : '';
+    const suggestion = directive.reason
+        ? `Review if this suppression is still needed: ${directive.reason}`
+        : 'Review if this suppression is still needed. Add a reason comment if keeping.';
+    return {
+        filePath: directive.filePath,
+        line: directive.line,
+        column: 0,
+        message: `[${directive.source}/${directive.scope}] ${directive.rule}${reasonPart}`,
+        severity: 'warning',
+        suggestion,
+        match: directive.raw,
+        type: `directive-${directive.source}`,
+    };
+}
+// =============================================================================
+// ANALYSIS
+// =============================================================================
+/**
+ * Analyze all files for suppression directives. Uses `analyzeAll`
+ * mode because directive auditing is naturally cross-file.
+ */
+async function analyzeAllFiles(files) {
+    const violations = [];
+    // @lazy-ok -- validations inside loop depend on file content from await
+    for (const filePath of files.paths) {
+        if (!isTypeScriptFile(filePath)) {
+            continue;
+        }
+        try {
+            const content = await files.read(filePath);
+            const file = getFileName(filePath);
+            if (!hasDirectiveMarkers(content)) {
+                continue;
+            }
+            const directives = collectFileDirectives(content, filePath, file);
+            for (const directive of directives) {
+                violations.push(directiveToViolation(directive));
+            }
+        }
+        catch {
+            // @swallow-ok Skip unreadable files
+        }
+    }
+    return violations;
+}
+// =============================================================================
+// CHECK DEFINITION
+// =============================================================================
+/**
+ * Check: documentation/directive-audit
+ *
+ * Audits all suppression directives (TypeScript, ESLint, fitness-ignore,
+ * semgrep) in the codebase for periodic review. This is an
+ * informational check that surfaces directives as warnings for audit
+ * purposes.
+ *
+ * Run via: `pnpm sip fit --check directive-audit`
+ */
+export const directiveAudit = defineCheck({
+    id: '9ffe898e-3f62-4ef1-9abd-63cf45174689',
+    slug: 'directive-audit',
+    scope: { languages: ['typescript'], concerns: ['backend', 'frontend', 'cli'] },
+    contentFilter: 'raw',
+    confidence: 'medium',
+    description: 'Audit suppression directives for periodic review',
+    longDescription: `**Purpose:** Surfaces all suppression directives across the codebase as warnings for periodic review, helping teams identify stale or unnecessary suppressions.
+
+**Detects:**
+- TypeScript directives: \`@ts-expect-error\` in \`//\` comments
+- ESLint directives: \`eslint-disable\`, \`eslint-disable-next-line\`, \`eslint-disable-line\` in both line (\`//\`) and block (\`/* */\`) comments
+- Fitness directives: \`@fitness-ignore-file\` and \`@fitness-ignore-next-line\` with check ID and \`--\` reason separator
+- Graph directives: \`@graph-ignore-file\` and \`@graph-ignore-next-line\` with \`graph:<rule>\` ID and \`--\` reason separator
+- Semgrep directives: \`nosemgrep\` with optional \`:\` rule ID and \`--\` reason separator
+- Classifies each directive by source, scope (file/next-line/same-line), rule, and reason
+- Only processes TypeScript files (\`.ts\`, \`.tsx\`), skips files without directive markers for performance
+
+**Why it matters:** Suppression directives accumulate over time and may outlive the conditions that justified them, silently weakening quality gates.
+
+**Scope:** General best practice. Cross-file analysis via \`analyzeAll\` scanning all TypeScript files. Disabled by default; run manually for periodic audits.`,
+    tags: ['documentation', 'audit', 'directives', 'maintenance'],
+    fileTypes: ['ts', 'tsx'],
+    disabled: true, // Run manually for periodic audits
+    analyzeAll: analyzeAllFiles,
+});
+//# sourceMappingURL=directive-audit.js.map

package/dist/checks/documentation/directive-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive-audit.js","sourceRoot":"","sources":["../../../src/checks/documentation/directive-audit.ts"],"names":[],"mappings":"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"}

package/dist/checks/documentation/index.d.ts

@@ -0,0 +1,3 @@
+export * from './directive-audit.js';
+export * from './public-api-jsdoc.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/checks/documentation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/checks/documentation/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC"}

package/dist/checks/documentation/index.js

@@ -0,0 +1,3 @@
+export * from './directive-audit.js';
+export * from './public-api-jsdoc.js';
+//# sourceMappingURL=index.js.map

package/dist/checks/documentation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/checks/documentation/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC"}

package/dist/checks/documentation/public-api-jsdoc.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Public API JSDoc check
+ */
+/**
+ * Check: documentation/public-api-jsdoc
+ *
+ * Requires JSDoc documentation on all public API exports in shared packages.
+ */
+export declare const publicApiJsdoc: import("@opensip-cli/fitness").Check;
+//# sourceMappingURL=public-api-jsdoc.d.ts.map

package/dist/checks/documentation/public-api-jsdoc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api-jsdoc.d.ts","sourceRoot":"","sources":["../../../src/checks/documentation/public-api-jsdoc.ts"],"names":[],"mappings":"AACA;;GAEG;AAmGH;;;;GAIG;AACH,eAAO,MAAM,cAAc,sCA2BzB,CAAC"}