@clossys/writer 0.4.0 → 0.5.1

package/dist/approval-bypass.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `scanApprovalBypass` and `checkApprovalBypass` — the APPROVAL-BYPASS gate:
+ * does consumer code route copy through the registry's approval lifecycle,
+ * or around it? Two patterns defeat that lifecycle while every other gate in
+ * this package stays green:
+ *
+ * 1. `approval-set-in-code` — the code itself declares approval: an object
+ *    property or member assignment named `approvedBy` or
+ *    `pendingOwnerReview`, or `status` set to the literal `"approved"`
+ *    (`{ ...entry, status: "approved" }`, `entry.status = "approved"`). An
+ *    approval typed into a component is an approval no owner ever gave.
+ * 2. `copy-read-without-resolver` — the code imports the registry file and
+ *    reads its content directly (`registry.entries.map(...)`, a spread, any
+ *    use other than the first argument of `createCopyResolver`,
+ *    `resolveCopyRef`, or `validateCopyRegistryShape`, or of
+ *    `parseCopyRegistry` only when its return value is passed to
+ *    `createCopyResolver` or `resolveCopyRef`).
+ *    A raw map built from the registry skips every lifecycle, staleness and
+ *    delegate check the resolver performs.
+ *
+ * ONLY REGISTRY-COUPLED FILES ARE EXAMINED — a file that imports from
+ * `@clossys/writer` (any subpath) or imports the registry file. That keeps a
+ * domain model with its own unrelated `status: "approved"` out of scope. It
+ * is a STATED LIMIT, not an oversight: a file that copies registry data
+ * without importing either (pasted JSON, data fetched at runtime, a registry
+ * passed in from an uncoupled module) is never seen by this gate.
+ *
+ * NO PARSER LIBRARY and no second tokenizer: every comment, string, template,
+ * regex and JSX-text boundary comes from `scan.ts`'s `maskNonCode`. The
+ * patterns here are matched against its masked `code` (so a comment or a
+ * string can never match), and literal values are looked up through its
+ * `literals` list. The heuristics that remain are narrow and local; each
+ * known gap is listed beside the function that has it.
+ *
+ * ============================================================================
+ * THE TERNARY
+ * ============================================================================
+ *
+ * The same precedence `addressability.ts` uses (issue #407): a definite
+ * finding outranks an incomplete picture.
+ *
+ *   - `"violated"` — at least one finding, regardless of unchecked positions.
+ *     `reasons` still lists any coverage gap.
+ *   - `"indeterminate"` — no finding, but an unchecked position (a dynamic or
+ *     otherwise unresolvable registry load, a string naming the registry), a
+ *     parse failure, or zero files scanned. Never a pass.
+ *   - `"satisfied"` — at least one file scanned, nothing unchecked, no
+ *     finding. Zero coupled files among ≥1 scanned file is satisfied.
+ */
+import type { ParseFailure, SkippedFile } from "./scan.js";
+export type { ParseFailure, SkippedFile } from "./scan.js";
+export interface ApprovalBypassScanOptions {
+    /** The copy registry file. Absolute, or relative to the scan `root`. Must exist. */
+    registryPath: string;
+    /** File extensions to read, each including the leading dot. Default: `.ts`, `.tsx`, `.js`, `.jsx`. */
+    extensions?: string[];
+    /** Directory names never descended into. Default: node_modules, .git, dist, build, coverage. */
+    skipDirs?: string[];
+}
+export type ApprovalBypassRule = "approval-set-in-code" | "copy-read-without-resolver";
+export interface ApprovalBypassFinding {
+    rule: ApprovalBypassRule;
+    severity: "error";
+    file: string;
+    line: number;
+    detail: string;
+}
+export interface ApprovalBypassUncheckedItem {
+    file: string;
+    line: number;
+    /** `"registry-dynamic-import"`, `"dynamic-import-non-literal"`, `"registry-require-unbound"`, `"require-non-literal"`, `"registry-reexport"` or `"registry-path-string"`. */
+    kind: string;
+    detail: string;
+}
+export interface ApprovalBypassScanResult {
+    /** Files successfully tokenized, coupled or not. Required to be > 0 for a satisfied verdict. */
+    filesScanned: number;
+    /** Root-relative paths of the files that were examined. */
+    coupledFiles: string[];
+    findings: ApprovalBypassFinding[];
+    unchecked: ApprovalBypassUncheckedItem[];
+    skippedByDesign: SkippedFile[];
+    parseFailures: ParseFailure[];
+}
+export type ApprovalBypassVerdict = "violated" | "indeterminate" | "satisfied";
+export interface ApprovalBypassGateResult {
+    verdict: ApprovalBypassVerdict;
+    findings: ApprovalBypassFinding[];
+    unchecked: ApprovalBypassUncheckedItem[];
+    /** Why coverage is incomplete. Empty for `"satisfied"`; may be non-empty for `"violated"`. */
+    reasons: string[];
+}
+export interface ApprovalBypassExtractResult {
+    coupled: boolean;
+    findings: ApprovalBypassFinding[];
+    unchecked: ApprovalBypassUncheckedItem[];
+    parseFailure?: string;
+}
+/**
+ * Walks `root`, examining every registry-coupled source file (see
+ * `extractApprovalBypass`). FAILS CLOSED — throws a plain `Error` — on an
+ * unreadable directory or file and on a missing registry file: either one
+ * means the scan cannot say what it did not see.
+ */
+export declare function scanApprovalBypass(root: string, options: ApprovalBypassScanOptions): ApprovalBypassScanResult;
+/**
+ * Pure — no I/O beyond `existsSync`/`realpathSync` for relative-specifier
+ * resolution. Decides whether `content` is registry-coupled and, if so,
+ * reports every approval-bypass finding and unchecked position in it.
+ * `filePath` is the path reported in results (and picks JSX masking for a
+ * `.tsx`/`.jsx` name); `context.absoluteFilePath` is where relative
+ * specifiers resolve from.
+ */
+export declare function extractApprovalBypass(content: string, filePath: string, context: {
+    registryPath: string;
+    absoluteFilePath: string;
+}): ApprovalBypassExtractResult;
+/** Pure — decides the ternary verdict from an already-computed scan. Never throws. See "THE TERNARY" above. */
+export declare function checkApprovalBypass(scan: ApprovalBypassScanResult): ApprovalBypassGateResult;
+//# sourceMappingURL=approval-bypass.d.ts.map

package/dist/approval-bypass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-bypass.d.ts","sourceRoot":"","sources":["../src/approval-bypass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE3D,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAI3D,MAAM,WAAW,yBAAyB;IACxC,oFAAoF;IACpF,YAAY,EAAE,MAAM,CAAC;IACrB,sGAAsG;IACtG,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GAAG,4BAA4B,CAAC;AAEvF,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,kBAAkB,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6KAA6K;IAC7K,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,gGAAgG;IAChG,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,SAAS,EAAE,2BAA2B,EAAE,CAAC;IACzC,eAAe,EAAE,WAAW,EAAE,CAAC;IAC/B,aAAa,EAAE,YAAY,EAAE,CAAC;CAC/B;AAED,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,eAAe,GAAG,WAAW,CAAC;AAE/E,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,SAAS,EAAE,2BAA2B,EAAE,CAAC;IACzC,8FAA8F;IAC9F,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,SAAS,EAAE,2BAA2B,EAAE,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAmBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,GAAG,wBAAwB,CAsE7G;AA8pDD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GAC1D,2BAA2B,CA0U7B;AAID,+GAA+G;AAC/G,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,wBAAwB,GAAG,wBAAwB,CAc5F"}