crewly 1.20.184 → 1.20.185

package/dist/backend/backend/src/scripts/check-oss-boundary.d.ts

@@ -0,0 +1,217 @@
+/**
+ * OSS/Pro boundary check (issue #809).
+ *
+ * CLAUDE.md Critical Rule 10 says premium/paid content never lives in the OSS
+ * repo. This module turns that prose into a check that fails when:
+ *
+ *  1. `paid-tier` — a JSON file under `config/templates/` declares
+ *     `requiredTier` of `pro` or `enterprise` (at any depth);
+ *  2. `pro-template-field` — a JSON template under `config/templates/`
+ *     defines a Pro-only top-level field (`workflows`,
+ *     `verificationPipeline`, `qualityGates`);
+ *  3. `premium-path` — a file path under `config/` has a segment starting
+ *     with `pro-` or containing `premium` (so `prompt`, `process-` and
+ *     `improve-` are not matched);
+ *  4. `pro-import` — an OSS source file imports or requires `crewly-pro` or
+ *     `@crewly/pro` (only real import/require specifiers count, never
+ *     comments or prose).
+ *
+ * Exceptions live in `config/oss-boundary-allowlist.json`, one entry per
+ * path with the rule it is exempt from and a one-line reason.
+ *
+ * Run locally or in CI with `npm run check:oss-boundary`; the jest suite also
+ * runs it against the real tree (see `check-oss-boundary.test.ts`).
+ *
+ * @module backend/scripts/check-oss-boundary
+ */
+import { OSS_BOUNDARY_CONSTANTS } from '../../../config/index.js';
+/** Identifier of one of the four boundary rules */
+export type OssBoundaryRule = (typeof OSS_BOUNDARY_CONSTANTS.RULES)[keyof typeof OSS_BOUNDARY_CONSTANTS.RULES];
+/** A single breach of the OSS/Pro boundary */
+export interface BoundaryViolation {
+    /** Which rule was broken */
+    rule: OssBoundaryRule;
+    /** Repository-relative path, always with `/` separators */
+    path: string;
+    /** Human-readable explanation of what was found */
+    detail: string;
+}
+/** An explicit, reasoned exception to one rule for one path */
+export interface AllowlistEntry {
+    /** Rule the path is exempt from */
+    rule: OssBoundaryRule;
+    /** Repository-relative path; a trailing `/` exempts everything below it */
+    path: string;
+    /** One-line reason the exception exists */
+    reason: string;
+}
+/** Outcome of a boundary check */
+export interface BoundaryReport {
+    /** Violations not covered by the allowlist — any of these fails the check */
+    violations: BoundaryViolation[];
+    /** Violations excused by an allowlist entry */
+    allowed: BoundaryViolation[];
+    /** Allowlist entries that matched nothing (stale; reported, not fatal) */
+    unusedAllowlistEntries: AllowlistEntry[];
+}
+/**
+ * Type guard for a rule identifier read from untrusted JSON.
+ *
+ * @param value - Candidate value
+ * @returns true when the value names one of the four rules
+ */
+export declare function isOssBoundaryRule(value: unknown): value is OssBoundaryRule;
+/**
+ * Recursively lists every file below a directory, skipping `node_modules`,
+ * `dist` and `.git`. A missing directory yields no files.
+ *
+ * @param dir - Absolute directory to walk
+ * @returns Absolute file paths, sorted for stable output
+ */
+export declare function listFiles(dir: string): string[];
+/**
+ * Finds every paid `requiredTier` declaration anywhere inside a JSON value.
+ *
+ * @param value - Parsed JSON
+ * @param pointer - JSON pointer of `value` (empty for the document root)
+ * @returns Human-readable descriptions of each paid-tier declaration
+ */
+export declare function findPaidTierDeclarations(value: unknown, pointer?: string): string[];
+/**
+ * Lists the Pro-only fields a template defines at its top level.
+ *
+ * @param value - Parsed template JSON
+ * @returns Names of the Pro-only fields present
+ */
+export declare function findProOnlyTemplateFields(value: unknown): string[];
+/**
+ * Returns the path segments that look like Pro or premium content: a segment
+ * that starts with `pro-` or contains `premium` (case-insensitive). Whole
+ * segments are tested so names like `prompt`, `process-` or `improve-` never
+ * match.
+ *
+ * @param repoPath - `/`-separated path
+ * @returns The offending segments, empty when the path is clean
+ */
+export declare function findPremiumSegments(repoPath: string): string[];
+/**
+ * Blanks out comments in JS/TS source while keeping string literals, so
+ * import specifiers can be matched without tripping on commented-out code
+ * or prose. Quoted strings end at a newline, which bounds the damage a
+ * regex literal containing a quote can do.
+ *
+ * @param source - Source text
+ * @returns The source with every comment replaced by spaces
+ */
+export declare function stripComments(source: string): string;
+/**
+ * Extracts the module specifiers a source file imports or requires.
+ *
+ * @param source - JS/TS source text
+ * @returns Every specifier found, in order of appearance per pattern
+ *
+ * @example
+ * ```typescript
+ * extractImportSpecifiers("import a from 'x'; const b = require('y');"); // ['x', 'y']
+ * ```
+ */
+export declare function extractImportSpecifiers(source: string): string[];
+/**
+ * Tells whether a specifier names a forbidden Pro package or one of its
+ * subpaths (e.g. `crewly-pro/dist/x`). Look-alikes such as `crewly-protocol`
+ * do not match.
+ *
+ * @param specifier - Module specifier
+ * @returns The forbidden package name, or null
+ */
+export declare function forbiddenPackageFor(specifier: string): string | null;
+/**
+ * Rules 1 and 2: scans JSON under `config/templates/`.
+ *
+ * @param repoRoot - Absolute repository root
+ * @returns Paid-tier and Pro-only-field violations
+ * @throws Error when a template file is not valid JSON
+ */
+export declare function checkTemplates(repoRoot: string): BoundaryViolation[];
+/**
+ * Rule 3: scans every file path under `config/` for Pro/premium segments.
+ *
+ * @param repoRoot - Absolute repository root
+ * @returns Premium-path violations
+ */
+export declare function checkConfigPaths(repoRoot: string): BoundaryViolation[];
+/**
+ * Lists the source roots rule 4 scans: the fixed roots plus each workspace
+ * package's `src` directory.
+ *
+ * @param repoRoot - Absolute repository root
+ * @returns Absolute directories (some may not exist; those scan as empty)
+ */
+export declare function sourceRoots(repoRoot: string): string[];
+/**
+ * Rule 4: scans OSS source for imports of the Pro package.
+ *
+ * @param repoRoot - Absolute repository root
+ * @returns Pro-import violations
+ */
+export declare function checkSourceImports(repoRoot: string): BoundaryViolation[];
+/**
+ * Validates the parsed allowlist document.
+ *
+ * @param value - Parsed allowlist JSON
+ * @param source - Where it came from, for error messages
+ * @returns The validated entries
+ * @throws Error when the document is not `{ "entries": [...] }` or an entry
+ *   lacks a known rule, a path or a non-empty one-line reason
+ */
+export declare function parseAllowlist(value: unknown, source: string): AllowlistEntry[];
+/**
+ * Loads the allowlist from the repository. A missing file means no
+ * exceptions.
+ *
+ * @param repoRoot - Absolute repository root
+ * @returns The validated entries
+ * @throws Error when the file exists but is malformed
+ */
+export declare function loadAllowlist(repoRoot: string): AllowlistEntry[];
+/**
+ * Tells whether an allowlist entry excuses a violation: same rule, and the
+ * path matches exactly or sits below an entry path ending in `/`.
+ *
+ * @param entry - Allowlist entry
+ * @param violation - Violation to test
+ * @returns true when the entry covers the violation
+ */
+export declare function allowlistCovers(entry: AllowlistEntry, violation: BoundaryViolation): boolean;
+/**
+ * Runs all four rules against a repository and applies the allowlist.
+ *
+ * @param repoRoot - Absolute repository root
+ * @param allowlist - Exceptions; defaults to the repository's allowlist file
+ * @returns Unexcused violations, excused ones and stale allowlist entries
+ * @throws Error when a template or the allowlist is malformed JSON
+ *
+ * @example
+ * ```typescript
+ * const report = checkOssBoundary(process.cwd());
+ * if (report.violations.length > 0) process.exit(1);
+ * ```
+ */
+export declare function checkOssBoundary(repoRoot: string, allowlist?: AllowlistEntry[]): BoundaryReport;
+/**
+ * Renders a report for the terminal / CI log.
+ *
+ * @param report - Result of {@link checkOssBoundary}
+ * @returns Multi-line text; starts with "OK" or "FAIL"
+ */
+export declare function formatReport(report: BoundaryReport): string;
+/**
+ * CLI entry: checks the repository and reports.
+ *
+ * @param repoRoot - Absolute repository root
+ * @param log - Sink for the passing report
+ * @param error - Sink for the failing report or a malformed-input error
+ * @returns Process exit code: success when no unexcused violations
+ */
+export declare function runCli(repoRoot: string, log?: (message: string) => void, error?: (message: string) => void): number;
+//# sourceMappingURL=check-oss-boundary.d.ts.map

package/dist/backend/backend/src/scripts/check-oss-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-oss-boundary.d.ts","sourceRoot":"","sources":["../../../../../backend/src/scripts/check-oss-boundary.ts"],"names":[],"mappings":"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"}