@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/dist/types/capabilities.d.ts

@@ -0,0 +1,64 @@
+import type { RuntimeExtension } from './extensions.ts';
+import type { CompiledRoute, CompiledRouteTable, LoadedDocument, PolicySupport, ProjectDocument, RouteConfig } from './types.ts';
+export declare const capabilityTargets: readonly ["self-hosted", "cloudflare", "aws", "vercel", "static"];
+export type CapabilityTarget = typeof capabilityTargets[number];
+export type CapabilitySupport = PolicySupport | 'conditional' | 'unknown';
+export declare const capabilityNames: readonly ["extension", "policies.extensions", "proxy", "signals", "conditional", "conditions", "redirect", "respond", "page", "static", "download", "function", "middleware", "parameters", "methods", "enabled", "expires", "request.body", "response.headers", "bindings", "policies.agents", "policies.security", "policies.cache", "policies.compression", "policies.throttle"];
+export type CapabilityName = typeof capabilityNames[number];
+/** The resolved operator registration set, when known (loaded via --host-file, same as `inspectExtensions`). Keyed by extension name. */
+export type ExtensionRegistry = ReadonlyMap<string, RuntimeExtension>;
+export interface CapabilityDecision {
+    support: CapabilitySupport;
+    reason: string;
+}
+export interface CapabilityRequirement extends CapabilityDecision {
+    path: string;
+    capability: CapabilityName;
+}
+export interface CompatibilityReport {
+    target: CapabilityTarget;
+    compatible: boolean;
+    requirements: CapabilityRequirement[];
+    issues: CapabilityRequirement[];
+    deployment: 'local-runtime' | 'unverified';
+}
+export interface CapabilityCatalog {
+    format: 1;
+    targets: {
+        target: CapabilityTarget;
+        deployment: CompatibilityReport['deployment'];
+    }[];
+    capabilities: {
+        capability: CapabilityName;
+        targets: Partial<Record<CapabilityTarget, CapabilityDecision>>;
+    }[];
+}
+export declare function normalizeCapabilityTarget(target: string): CapabilityTarget;
+/** Catalog, not a claim that every configuration or provider deployment works. */
+export declare function getCapabilities(target?: string): CapabilityCatalog;
+/** A safe projection shared by declaration preflight and the existing compiled IR. No values escape. */
+export declare function routeCapabilities(route: RouteConfig | CompiledRoute, document: ProjectDocument): CapabilityName[];
+/**
+ * Preflight only: call after schema validation/site expansion, before resolving bindings.
+ * `registrations` is the resolved operator extension set, when known (the same
+ * shape --host-file loads for `inspectExtensions`); without it, `extension`/
+ * `policies.extensions` requirements report `conditional`/`unknown` rather
+ * than a blanket `native` that ignores the specific extension's own targets.
+ */
+export declare function analyzeProjectCapabilities(loaded: LoadedDocument, target: string, registrations?: readonly RuntimeExtension[]): CompatibilityReport;
+/** Analyze normalized route semantics without exporting validators, resources or resolved secrets. */
+export declare function analyzeCompiledCapabilities(document: ProjectDocument, compiled: CompiledRouteTable, target: string, registrations?: readonly RuntimeExtension[]): CompatibilityReport;
+export declare function assertTargetCompatibility(report: CompatibilityReport): void;
+export declare function formatCapabilities(catalog: CapabilityCatalog): string;
+export type CapabilityKind = 'handler' | 'policy' | 'routing' | 'request' | 'binding' | 'egress' | 'middleware' | 'project';
+export interface CapabilityDetail {
+    kind: CapabilityKind;
+    summary: string;
+    /** Dotted schema paths (`urlcode schema <path>`) whose fragments describe this capability's YAML. */
+    schema: string[];
+    constraints: string[];
+    /** Operator authority the capability needs at activation; never binding values. */
+    grants: string[];
+}
+/** Static facts about each catalog entry. Per-target support stays in `decision`; recipe and cookbook usage is scanned by `getCapability`. */
+export declare const capabilityDetails: Record<CapabilityName, CapabilityDetail>;

package/dist/types/capability-query.d.ts

@@ -0,0 +1,24 @@
+import { formatCapabilities } from './capabilities.ts';
+import type { CapabilityDecision, CapabilityDetail, CapabilityName, CapabilityTarget } from './capabilities.ts';
+import type { SchemaFragment } from './schema-query.ts';
+export interface CapabilityUsage {
+    file: string;
+    routes: string[];
+}
+export interface CapabilityEntry extends CapabilityDetail {
+    format: 1;
+    name: CapabilityName;
+    schemaFragments: SchemaFragment[];
+    targets: Record<CapabilityTarget, CapabilityDecision>;
+    refused: {
+        target: CapabilityTarget;
+        reason: string;
+    }[];
+    recipes: CapabilityUsage[];
+    cookbook: CapabilityUsage[];
+}
+export declare function capabilityNameList(): readonly CapabilityName[];
+/** One catalog entry with its schema fragments and bundled usage. No project, credentials or network are read. */
+export declare function getCapability(name: string): CapabilityEntry;
+export declare function formatCapability(entry: CapabilityEntry): string;
+export { formatCapabilities };

package/dist/types/catalog.d.ts

@@ -0,0 +1,65 @@
+import type { CapabilityName, CapabilityTarget } from './capabilities.ts';
+/**
+ * The metadata shape shared by recipes/NAME/recipe.yaml and examples/NAME/example.yaml
+ * (schemas/recipe.schema.json). The catalog entries are fixed package data: names
+ * come from a list in code, never from a directory scan, a registry or an argument.
+ */
+export type TargetVerdict = 'compatible' | 'conditional' | 'refused' | 'unknown';
+export type Complexity = 'starter' | 'intermediate' | 'advanced';
+export interface CatalogMetadata {
+    id: string;
+    description: string;
+    tags: string[];
+    complexity: Complexity;
+    runnable?: boolean;
+    capabilities?: string[];
+    targets?: Record<CapabilityTarget, TargetVerdict>;
+    routes?: number;
+    services?: {
+        name: string;
+        description: string;
+    }[];
+    grants?: {
+        kind: string;
+        description: string;
+    }[];
+    inputs?: {
+        name: string;
+        file: string;
+        description: string;
+    }[];
+    files: string[];
+    tests?: {
+        fixtures?: string;
+        commands: string[];
+    };
+    behavior?: string[];
+}
+/** The fields the capability preflight determines; `npm run check` refuses hand-written values that differ. */
+export interface DerivedMetadata {
+    capabilities: CapabilityName[];
+    targets: Record<CapabilityTarget, TargetVerdict>;
+    routes: number;
+}
+export interface SearchHit<T extends CatalogMetadata> {
+    entry: T;
+    score: number;
+    matched: string[];
+}
+export declare const metadataFiles: {
+    readonly recipe: "recipe.yaml";
+    readonly example: "example.yaml";
+};
+/** Reads and schema-validates one metadata file; the id must equal the directory name, and file lists stay authoring-safe paths. */
+export declare function readMetadata(root: string, id: string, file: 'recipe.yaml' | 'example.yaml'): Promise<CatalogMetadata>;
+/** Preflight only: loads the project, expands site routes and asks the capability analysis for every target. No bindings, code or activation. */
+export declare function deriveMetadata(root: string): Promise<DerivedMetadata>;
+/** Reports where hand-written derived fields disagree with the preflight; empty means consistent. */
+export declare function derivedDifferences(metadata: CatalogMetadata, derived: DerivedMetadata): string[];
+export declare function searchTerms(text: string): string[];
+/**
+ * Local search over id, description, tags and capabilities: every term must match
+ * somewhere; the score prefers whole-tag and id hits over description substrings.
+ * Ties keep catalog order, so the smallest entry wins when a caller sorts by size first.
+ */
+export declare function searchMetadata<T extends CatalogMetadata>(entries: readonly T[], text: string, extraText?: (entry: T) => string[]): SearchHit<T>[];

package/dist/types/client-address.d.ts

@@ -4,6 +4,5 @@ export interface Cidr {
 }
 export declare function parseCidr(text: string): Cidr;
 export declare function compileTrustedProxies(list?: string | string[]): Cidr[];
-export declare function isTrustedProxy(address: string, trusted: Cidr[]): boolean;
 export declare function resolveClient(peer: string | undefined, forwarded: string | undefined, trusted: Cidr[]): string | undefined;
 export declare function normalizeAddress(address: unknown): string | undefined;

package/dist/types/compliance-rules/baseline.d.ts

@@ -1,12 +1,4 @@
-import type { ComplianceRule, ProjectRule, RouteRule } from '../compliance.ts';
+import type { ComplianceRule, ProjectRule } from '../compliance.ts';
 export declare const profile = "baseline";
-export declare const securityHeaders: RouteRule;
-export declare const hstsOrigin: ProjectRule;
-export declare const secretsCompression: RouteRule;
-export declare const secretsNoStore: RouteRule;
-export declare const cacheControlDeclared: RouteRule;
-export declare const throttleFunctions: RouteRule;
 export declare const robots: ProjectRule;
-export declare const expiredRoutes: ProjectRule;
-export declare const managementPrivate: ProjectRule;
 export declare const rules: readonly ComplianceRule[];

package/dist/types/compliance-rules/privacy.d.ts

@@ -1,6 +1,3 @@
-import type { ComplianceRule, ProjectRule, RouteRule } from '../compliance.ts';
+import type { ComplianceRule } from '../compliance.ts';
 export declare const profile = "privacy";
-export declare const requestLogMinimal: ProjectRule;
-export declare const linkEventsOff: ProjectRule;
-export declare const detailedParameters: RouteRule;
 export declare const rules: readonly ComplianceRule[];

package/dist/types/compliance-rules/shared.d.ts

@@ -7,8 +7,6 @@ export declare const rfc6585: Standard;
 export declare const rfc9309: Standard;
 export declare const breach: Standard;
 export declare const monitoring: Standard;
-export declare const linkChannel: Standard;
-export declare const management: Standard;
 export declare const agentLists: Standard;
 export declare const active: (route: PlanInventoryEntry) => boolean;
 export declare const functionLike: (route: PlanInventoryEntry) => boolean;

package/dist/types/compliance-rules/strict.d.ts

@@ -1,9 +1,4 @@
 import type { ComplianceRule, RouteRule } from '../compliance.ts';
 export declare const profile = "strict";
-export declare const headerBudgetBytes = 8192;
 export declare const csp: RouteRule;
-export declare const throttleAll: RouteRule;
-export declare const listsPinned: RouteRule;
-export declare const redirectHttps: RouteRule;
-export declare const headerBudget: RouteRule;
 export declare const rules: readonly ComplianceRule[];

package/dist/types/compliance.d.ts

@@ -27,8 +27,6 @@ export type RuleResult = RawFinding[] | RawFinding | null | undefined | false;
 /** The host settings under review, null where the operator declared nothing. */
 export interface HostSettings {
     requestLog: 'minimal' | 'detailed' | null;
-    linkEvents: boolean | null;
-    includeCode: boolean | null;
 }
 export interface ProjectContext {
     document: ProjectDocument;
@@ -92,7 +90,6 @@ export interface ComplianceReport {
     evidence: {
         routes: number;
         active: number;
-        dynamicLinks: boolean;
         policies: string[];
         files: string[];
         origin: string | null;

package/dist/types/conditions.d.ts

@@ -0,0 +1,19 @@
+/** Bounded conjunction of exact string comparisons; no regex or implicit detection. */
+export interface RouteMatch {
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    cookies?: Record<string, string>;
+    host?: string;
+    method?: string;
+}
+export interface ConditionRequest {
+    query: URLSearchParams;
+    headers: Headers;
+    method: string;
+    origin: string;
+    headerCounts?: Record<string, number> | undefined;
+}
+export declare function normalizeMatch(match: RouteMatch): RouteMatch;
+/** Cases must be disjoint: at least one shared fact must demand different values. */
+export declare function assertDisjointMatches(matches: RouteMatch[]): void;
+export declare function matchesRoute(match: RouteMatch, request: ConditionRequest): boolean;

package/dist/types/config.d.ts

@@ -1,4 +1,4 @@
-import type { LoadedDocument, ProjectDocument } from './types.ts';
+import type { AuthoredRouteConfig, LoadedDocument, ProjectDocument, RouteConfig } from './types.ts';
 /** What config-worker.ts posts back: the loaded document, or the ConfigError message. */
 export type ConfigWorkerResult = {
     value: LoadedDocument;
@@ -11,11 +11,30 @@ export interface ConfigWorkerData {
 export declare const MAX_CONFIG_BYTES: number;
 export declare function parseYaml(text: string): unknown;
 export declare function validateDocument(data: unknown): ProjectDocument;
+/** The input declaration a short-form function gets for each `{param}` it does not declare itself. */
+export declare const SHORT_FORM_PATH_SCHEMA: {
+    readonly type: "string";
+    readonly minLength: 1;
+    readonly maxLength: 128;
+};
+/**
+ * Expands the YAML short forms into the canonical long form. `function: functions/x.mjs`
+ * becomes `{source, args}` with an argument per `{param}` in the path, declaring any
+ * parameter the route does not declare itself; a string middleware entry becomes `{source}`;
+ * a route-level `cache` becomes `policies.cache` (refused alongside a direct `policies.cache`).
+ * Everything downstream (routes, audit, the compiled table) sees only the long form.
+ */
+export declare function normalizeRoute(pattern: string, route: AuthoredRouteConfig | RouteConfig): RouteConfig;
 export declare function safeFile(root: string, file: unknown): Promise<string>;
-export declare const MAX_PROJECT_CONFIG_BYTES: number;
 export declare function loadDocument(project: string, { timeoutMs }?: {
     timeoutMs?: number;
 }): Promise<LoadedDocument>;
+/**
+ * Expands the route-level `auth` short form into the canonical `policies.extensions.auth` requirement so every
+ * downstream consumer (compiler, routes, audit, explain, revision hash) sees one form. `auth: {required: false}`
+ * documents intent and emits nothing. Refuses routes that use both forms or lack an `extensions.auth` declaration.
+ */
+export declare function normalizeRouteAuth(document: Pick<ProjectDocument, 'extensions'>, routes: Record<string, RouteConfig>): void;
 export declare function loadDocumentInWorker(project: string): Promise<LoadedDocument>;
 export declare function loadBindings(root: string, local?: boolean, environment?: Record<string, string | undefined>): Promise<Record<string, string | undefined>>;
 export declare function functionFile(root: string, file: string): Promise<string>;

package/dist/types/context.d.ts

@@ -0,0 +1,66 @@
+export interface ContextOptions {
+    /** Restrict the target table to one capability target. */
+    target?: string | undefined;
+    /** Absolute path to a trusted operator host module outside the project; its extensions and plugins are counted, never run. */
+    hostFile?: string | undefined;
+    /** Estimated token budget; sections are dropped in a fixed order until the YAML rendering fits. */
+    budget?: number | undefined;
+    /** What `--project` should say in the emitted commands; defaults to the project argument itself. */
+    projectFlag?: string | undefined;
+}
+export type ContextSection = 'routes' | 'targets' | 'constraintNotes' | 'files' | 'commands' | 'summary';
+export interface ProjectContext {
+    urlcode: string;
+    schema: '1';
+    project: {
+        entry: string;
+        routes: number;
+        handlers: Record<string, number>;
+        extensions: string[];
+        policies: {
+            project: string[];
+            routes: Record<string, number>;
+        };
+        bindings: {
+            env: string[];
+            secrets: string[];
+        };
+        site: string[];
+        files?: {
+            includes: string[];
+            functions: string[];
+            middleware: string[];
+        };
+        host?: {
+            extensions: string[];
+            plugins: number;
+        };
+    };
+    routes?: {
+        path: string;
+        methods: string[];
+        handler: string;
+        sandbox: boolean;
+        sandboxReason?: string;
+    }[];
+    constraints: Record<string, boolean | string | {
+        value: boolean | string;
+        note: string;
+    }>;
+    targets?: Record<string, {
+        deployment: string;
+        supported: string[];
+        conditional: string[];
+        refused: string[];
+        unknown: string[];
+    }>;
+    commands?: Record<string, string>;
+    omitted?: ContextSection[];
+}
+/** Characters divided by four, rounded up: an estimate, not a tokenizer. */
+export declare function estimateTokens(text: string): number;
+export declare function renderContext(context: ProjectContext): string;
+/** Derived only from the compiled project and the capability catalog, never from prose. Key order is fixed. */
+export declare function buildContext(project: string, options?: ContextOptions): Promise<ProjectContext>;
+/** Estimated size of the shipped documentation (docs/*.md and llms.txt), for comparison with an emitted context. */
+export declare function documentationTokens(): Promise<number>;

package/dist/types/ecosystem-cli.d.ts

@@ -0,0 +1,17 @@
+interface Options {
+    json?: boolean | undefined;
+    project: string;
+    out?: string | undefined;
+    format?: string | undefined;
+    input?: string | undefined;
+    target?: string | undefined;
+    origin?: string | undefined;
+    'dry-run'?: boolean | undefined;
+    'timeout-ms'?: string | undefined;
+    release?: string | undefined;
+    'git-commit'?: string | undefined;
+    'allow-authoring'?: boolean | undefined;
+    'host-file'?: string | undefined;
+}
+export declare function runEcosystemCommand(command: string, args: string[], options: Options, print: (value: unknown) => unknown): Promise<void>;
+export {};

package/dist/types/egress.d.ts

@@ -0,0 +1,46 @@
+import { request } from 'node:https';
+export declare const EGRESS_DNS_LIMIT = 64;
+export interface EgressRequest {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    body?: Uint8Array;
+    signal?: AbortSignal;
+}
+export interface EgressResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: Buffer;
+}
+export interface EgressOptions {
+    grantOrigins: string[];
+    timeoutMs?: number;
+    maxRequestBytes?: number;
+    maxResponseBytes?: number;
+    maxHeaderBytes?: number;
+    concurrency?: number;
+}
+type EgressErrorCode = 'denied' | 'busy' | 'closed' | 'aborted' | 'timeout' | 'limit' | 'upstream';
+export declare class EgressError extends Error {
+    readonly code: EgressErrorCode;
+    constructor(code: EgressErrorCode);
+}
+/** Conservative public-unicast filter. IPv4-mapped IPv6 and transition mechanisms are denied. */
+export declare function isPublicAddress(address: string): boolean;
+export declare function egressUrl(value: string): URL;
+export declare function safeEgressHeaders(headers: Record<string, string>, maxBytes?: number): Record<string, string>;
+/** Operator-owned transport. Never exposed to guests. Each request has its own nonpooled socket. */
+export interface EgressDependencies {
+    resolve?: (hostname: string) => Promise<{
+        address: string;
+        family: number;
+    }[]>;
+    request?: typeof request;
+}
+export declare class EgressClient {
+    #private;
+    constructor(options: EgressOptions, dependencies?: EgressDependencies);
+    request(input: EgressRequest): Promise<EgressResponse>;
+    close(): Promise<void>;
+}
+export {};

package/dist/types/examples.d.ts

@@ -0,0 +1,50 @@
+import type { CatalogMetadata } from './catalog.ts';
+/** example.yaml, the same schema as recipe.yaml; `name` repeats `id`. */
+export interface ExampleSummary extends CatalogMetadata {
+    name: string;
+}
+/** One cookbook route in the generated tag index (examples/cookbook/route-index.json). */
+export interface RouteIndexEntry {
+    path: string;
+    file: string;
+    handler: string;
+    methods: string[];
+    tags: string[];
+    description: string;
+}
+export interface RouteIndex {
+    format: 1;
+    project: string;
+    routes: number;
+    entries: RouteIndexEntry[];
+}
+export interface ExampleSearchResult {
+    query: string;
+    count: number;
+    /** The smallest matching runnable example, and its best matching cookbook route when the cookbook is that example. */
+    best: (ExampleSummary & {
+        route?: RouteIndexEntry;
+    }) | null;
+    results: (ExampleSummary & {
+        score: number;
+        matched: string[];
+        matchedRoutes: RouteIndexEntry[];
+    })[];
+}
+export declare const exampleNames: readonly ["assets", "aws", "cloudflare", "compliance", "conditions", "cookbook", "egress", "extensions", "monitoring", "prerender", "provider-conformance", "tunnel", "vercel"];
+export declare const routeIndexFile = "route-index.json";
+export declare function listExamples(): Promise<ExampleSummary[]>;
+/**
+ * Derives the per-route tag index of one project from its loaded routes: handler,
+ * methods, capabilities, policy names and middleware module names. The file each
+ * route comes from is read from the entry and its includes; routes that neither
+ * declares were generated by `site`.
+ */
+export declare function buildRouteIndex(project: string, label: string): Promise<RouteIndex>;
+export declare function readRouteIndex(name: string): Promise<RouteIndex>;
+/**
+ * Searches example.yaml files and the cookbook's per-route index locally. Results
+ * are ordered smallest runnable example first, so `best` is the least code that
+ * demonstrates the match; cookbook hits carry their matching routes.
+ */
+export declare function searchExamples(text: string): Promise<ExampleSearchResult>;

package/dist/types/explain-cli.d.ts

@@ -0,0 +1,11 @@
+import type { RuntimeExtension } from './extensions.ts';
+interface Options {
+    project: string;
+    target?: string | undefined;
+    origin?: string | undefined;
+    json?: boolean | undefined;
+    extensions?: RuntimeExtension[] | undefined;
+}
+/** Returns the process exit code: 1 when a requested route does not exist. */
+export declare function runExplainCommand(command: 'explain' | 'manifest', route: string | undefined, options: Options, print: (value: unknown) => unknown): Promise<number>;
+export {};

package/dist/types/explain.d.ts

@@ -0,0 +1,95 @@
+import type { CapabilityName, CapabilityTarget } from './capabilities.ts';
+import type { RuntimeExtension } from './extensions.ts';
+import type { CompiledRoute, LoadedDocument, PolicyChain, PolicyInventory, RouteState } from './types.ts';
+import type { HandlerName } from './readiness.ts';
+import type { ParameterSchema, ParameterLocation } from './match.ts';
+import type { RequestBodyPolicy } from './http-policy.ts';
+export interface ExplainedHandler {
+    kind: HandlerName | 'none';
+    [detail: string]: unknown;
+}
+export interface ExplainedParameter {
+    name: string;
+    in: ParameterLocation;
+    required: boolean;
+    schema: ParameterSchema;
+}
+export interface ExtensionProvider {
+    registered: boolean;
+    version?: string;
+    targets?: string[];
+    revisionMatch?: boolean;
+    requirementValid?: boolean | null;
+}
+export interface ExplainedExtensionRequirement {
+    requirement: Record<string, unknown>;
+    provider?: ExtensionProvider;
+}
+export interface ExplainedCache {
+    /** What a response from this route carries: the policy strategy, the header source or `none`. */
+    outcome: string;
+    cacheControl?: string;
+    forcedNoStore: boolean;
+    reason?: string;
+}
+export interface TargetSupport {
+    compatible: boolean;
+    issues: {
+        capability: CapabilityName;
+        support: string;
+        reason: string;
+    }[];
+}
+export interface RouteExplanation {
+    matched: true;
+    path: string;
+    description?: string;
+    generated?: string;
+    state: RouteState;
+    enabled: boolean;
+    expires?: string;
+    methods: string[];
+    conditional: boolean;
+    handler: ExplainedHandler;
+    middleware: {
+        source: string;
+        export: string;
+    }[];
+    inputs: {
+        parameters: ExplainedParameter[];
+        body?: RequestBodyPolicy;
+    };
+    policies: {
+        names: string[];
+        inventory: PolicyInventory;
+        extensions: Record<string, ExplainedExtensionRequirement>;
+    };
+    cache: ExplainedCache;
+    bindings: {
+        env: Record<string, {
+            env: string;
+        } | {
+            literal: true;
+        }>;
+        secrets: Record<string, {
+            secret: string;
+        }>;
+    };
+    egress: {
+        proxy?: string;
+        signals?: string[];
+    };
+    responseHeaders: [string, string][];
+    capabilities: CapabilityName[];
+    targets: Record<CapabilityTarget, TargetSupport>;
+    note: string;
+}
+export interface ExplainOptions {
+    extensions?: RuntimeExtension[] | undefined;
+    projectSha256?: string | undefined;
+    now?: number | undefined;
+}
+export declare function routeState(route: CompiledRoute, now: number): RouteState;
+/** Describe one compiled route. `chain` is the policy chain compiled for it, when the project declares policies. */
+export declare function explainCompiledRoute(loaded: LoadedDocument, route: CompiledRoute, chain: PolicyChain | undefined, options?: ExplainOptions): RouteExplanation;
+export declare function nearestRoutes(target: string, patterns: Iterable<string>, limit?: number): string[];