polycast-cli 0.2.0 → 0.3.0

package/dist/scan.d.ts

@@ -1,27 +1,83 @@
 /**
- * Zero-config source capture: scan Swift files for Polycast-rendered
- * string literals so nobody hand-maintains the String Catalog.
+ * Zero-config source capture: a Swift-aware lexer + capture engine that
+ * finds Polycast-rendered string literals in Swift sources so nobody
+ * hand-maintains the String Catalog.
  *
- * Captured calls: Text("…"), PText("…"), Polycast.string("…").
- * (With the generated `typealias Text = PText` shadow, plain Text renders
- * through Polycast, so its literals belong in the pipeline too.)
+ * The lexer understands the real literal grammar — escapes (\n \t \\ \"
+ * \r \0 \u{XXXX} decoded), multiline """…""" blocks (closing-delimiter
+ * indentation stripped, physical newlines preserved), raw #"…"# /
+ * #"""…"""# strings (backslash is literal unless followed by the matching
+ * number of #s), nested block comments, and strings containing "//" — so
+ * comment handling can never misfire inside a literal.
  *
- * Interpolations become %@ — identical to PolycastFormatString at
- * runtime, so scanned keys and rendered keys always agree.
- * `Text(verbatim:)` and empty literals are skipped;
- * `…, count: n)` marks a plural key.
+ * Interpolations `\(…)` become %@ — identical to PolycastFormatString at
+ * runtime, so scanned keys and rendered keys always agree byte-for-byte.
+ * Parity rule: a literal "%" doubles to "%%" ONLY when the string contains
+ * at least one interpolation ("Save 50% off \(deal)" → "Save 50%% off %@";
+ * a pure literal "Save 50%" stays "Save 50%").
+ *
+ * Captured shapes:
+ *  - registered calls (Text, PText, Polycast.string, …): every top-level
+ *    literal in the balanced argument list — ternary branches, `??`
+ *    fallbacks, paren-wrapped expressions, 2nd+ positional args. Literals
+ *    behind a SKIP label (verbatim:, systemImage:, …), inside nested
+ *    closures `{ … }`, or inside subscripts/collection literals `[ … ]`
+ *    are not display strings and are skipped.
+ *  - qualified spellings: SwiftUI.Text(…) and Text.init(…). SwiftUI.-
+ *    qualified captures are marked `native` (they opt out of the shadow).
+ *  - Foundation: NSLocalizedString("key", …) (first literal only),
+ *    String(localized:…), AttributedString(localized:…).
+ *  - `.prop = "literal"` assignments for a configurable property list.
+ *  - `: String = "literal"` typed defaults (vars, lets, default params).
+ *  - `title:`-style registered labels in any argument position.
+ * A `comment:`-labelled literal becomes the translator note for its call.
  */
 export interface ScannedString {
     key: string;
     kind: "simple" | "plural";
     file: string;
+    /** Translator note from a `comment:` argument at the capture site. */
+    comment?: string;
+    /** Letterless "joiner" key ("%@ – %@"): stored and served in bundles,
+     * but skipped by AI drafting. */
+    structural?: boolean;
+    /** Every occurrence used the SwiftUI-qualified spelling (`SwiftUI.Text`),
+     * which opts out of the Polycast shadow — OTA edits won't reach it. */
+    native?: boolean;
+}
+export interface ScanStats {
+    filesScanned: number;
+    dirsSkipped: string[];
+    rootsScanned: string[];
+}
+export interface ScanOptions {
+    /** Extra capture spellings, same syntax as polycast.json `scanCalls`:
+     * "AppText" (call), ".navigationTitle" (method), "title:" (label). */
+    extraCalls?: string[];
+    /** Property names captured via `.prop = "literal"`; REPLACES
+     * DEFAULT_ASSIGN_PROPS when provided. */
+    assignProps?: string[];
+    /** Directory recursion depth limit (default 12). */
+    maxDepth?: number;
+    /** Directory names to skip; REPLACES the default skip list when
+     * provided. Dot-directories are always skipped. */
+    skipDirs?: string[];
+    /** Extra roots scanned in addition to `root` (relative paths resolve
+     * against `root`). Local SPM path deps from Package.swift are
+     * auto-discovered on top of these. */
+    extraRoots?: string[];
+    /** Per-file predicate over the path relative to the main root (the same
+     * value ScannedString.file carries); return false to skip the file.
+     * Applied BEFORE capture and cross-file dedupe, so a key denied in one
+     * file still survives via its occurrences in allowed files. */
+    fileFilter?: (relPath: string) => boolean;
 }
 export declare const DEFAULT_SCAN_CALLS: string[];
-/** Build the call matcher from default + user-configured component names.
- * Plain names ("AppText") match constructor/function calls; names starting
- * with "." (".navigationTitle") match method calls. */
-export declare function buildCallMatcher(extra?: string[]): RegExp;
+/** `.prop = "literal"` assignment targets captured by default. */
+export declare const DEFAULT_ASSIGN_PROPS: string[];
+export declare function scanSwiftSourcesDetailed(root: string, opts?: ScanOptions): {
+    strings: ScannedString[];
+    stats: ScanStats;
+};
+/** Back-compat wrapper — same shape the CLI has always consumed. */
 export declare function scanSwiftSources(root: string, extraCalls?: string[]): ScannedString[];
-/** Blank out line and block comments (string-literal aware) so doc
- * examples like `Text("…")` never get captured. Nested blocks handled. */
-export declare function stripComments(src: string): string;