canary-test-cli 6.1.0 → 6.3.0

package/dist/engine/analysis/reachability.js

@@ -0,0 +1,305 @@
+/**
+ * Reachability sweep — the generic crawl primitive from #452.
+ *
+ * Enumerate every link on a surface and assert it resolves. Cheap, broad, and
+ * high-yield: it catches dangling routes and 404s that targeted tests never
+ * look for, because a targeted test asserts what a page *does*, not that the
+ * things it points at still exist.
+ *
+ * This module owns the deterministic half — normalization, scoping, and
+ * classification. **Fetching is injected** ({@link LinkProbe}), so the logic is
+ * unit-testable with no network and a caller can supply whatever transport it
+ * already has (plain `fetch`, an authenticated client, a browser page).
+ *
+ * ## The load-bearing distinction: dead vs. slow
+ *
+ * The reason this is not simply "fetch and check the status": **a dead link and
+ * a slow link must never be confusable.** A 404 is a defect the sweep is
+ * entitled to assert on. A timeout, DNS failure, or refused connection is
+ * *inconclusive* — the link may be perfectly fine while the network, a cold
+ * container, or a rate limiter is not.
+ *
+ * Conflating them is how a broad sweep turns into a flaky test that teams learn
+ * to ignore, which costs more than the check was ever worth. So the two are
+ * structurally different outcomes ({@link ReachabilityStatus.Broken} vs
+ * {@link ReachabilityStatus.Unreachable}) with different {@link isDefect}
+ * verdicts, and only the first is ever asserted on.
+ *
+ * The same principle decides the other ambiguous cases:
+ *   - **5xx** — the target exists and is unwell. A server problem, not a
+ *     dangling reference; blaming the link sends someone to fix the wrong
+ *     thing.
+ *   - **401/403** — auth-walled, not missing. The link is fine; the sweep just
+ *     is not logged in.
+ *
+ * Only an unambiguous "this target does not exist" (4xx that is not auth)
+ * counts as a defect.
+ */
+/** How a probed link resolved. Only {@link Broken} is asserted on. */
+export var ReachabilityStatus;
+(function (ReachabilityStatus) {
+    /** Resolved (2xx/3xx), or exists but is auth-walled (401/403). */
+    ReachabilityStatus["Ok"] = "ok";
+    /** The target does not exist (4xx other than auth). The one real defect. */
+    ReachabilityStatus["Broken"] = "broken";
+    /** The target exists but errored (5xx) — a server problem, not a bad link. */
+    ReachabilityStatus["ServerError"] = "server-error";
+    /** No verdict possible: timeout, DNS failure, refused connection. */
+    ReachabilityStatus["Unreachable"] = "unreachable";
+    /** Off-site and not allowlisted, so deliberately not probed. */
+    ReachabilityStatus["SkippedExternal"] = "skipped-external";
+})(ReachabilityStatus || (ReachabilityStatus = {}));
+// Schemes that are not fetchable resources. A `mailto:`/`tel:` is a valid link
+// and probing it is meaningless; `javascript:` is a control, not a destination.
+const NON_FETCHABLE_SCHEMES = new Set([
+    'mailto:',
+    'tel:',
+    'javascript:',
+    'data:',
+    'blob:',
+    'sms:',
+    'file:',
+]);
+/** Auth-walled: the target exists, the sweep just cannot see it. */
+const AUTH_STATUSES = new Set([401, 403]);
+/**
+ * Resolve `href` against `base` into an absolute, fragment-free URL.
+ *
+ * Returns `null` for anything that is not a fetchable destination: an empty or
+ * fragment-only href (it points at the current page), a non-fetchable scheme,
+ * or an href malformed enough that `URL` rejects it.
+ *
+ * The fragment is dropped deliberately — `/p#a` and `/p#b` are the same
+ * request, and keeping them apart would probe the same page repeatedly and
+ * report one dangling route as several.
+ */
+export function normalizeLink(href, base) {
+    const trimmed = href.trim();
+    // Empty, or a pure fragment: this is the current page, not a destination.
+    if (!trimmed || trimmed.startsWith('#'))
+        return null;
+    let url;
+    try {
+        url = new URL(trimmed, base);
+    }
+    catch {
+        return null;
+    }
+    if (NON_FETCHABLE_SCHEMES.has(url.protocol))
+        return null;
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return null;
+    url.hash = '';
+    return { url: url.href, host: url.hostname };
+}
+/** True iff `host` is `allowed` or a subdomain of it (never a lookalike). */
+function hostMatches(host, allowed) {
+    const h = host.toLowerCase();
+    const a = allowed.toLowerCase();
+    // The leading dot is what stops `nottrusted.example` matching
+    // `trusted.example` — a bare `endsWith` would wrongly accept it.
+    return h === a || h.endsWith(`.${a}`);
+}
+/** True iff `link` is in scope: same host as the base, or allowlisted. */
+function inScope(link, baseHost, allowExternal) {
+    if (hostMatches(link.host, baseHost))
+        return true;
+    return allowExternal.some((allowed) => hostMatches(link.host, allowed));
+}
+/** Map an HTTP status to a verdict. See the module docstring for the rationale. */
+function classifyStatus(status) {
+    if (status >= 200 && status < 400)
+        return ReachabilityStatus.Ok;
+    // Auth-walled is not dangling: the target exists.
+    if (AUTH_STATUSES.has(status))
+        return ReachabilityStatus.Ok;
+    if (status >= 400 && status < 500)
+        return ReachabilityStatus.Broken;
+    if (status >= 500)
+        return ReachabilityStatus.ServerError;
+    // 1xx as a final status is nonsensical; refuse to guess.
+    return ReachabilityStatus.Unreachable;
+}
+/**
+ * True iff `status` is a finding worth failing a sweep on.
+ *
+ * Only {@link ReachabilityStatus.Broken}. `Unreachable` is inconclusive,
+ * `ServerError` belongs to whoever owns the server, and a skipped link was
+ * never claimed to be checked. Asserting on any of those would make the sweep
+ * fail for reasons the author of the link cannot fix.
+ */
+export function isDefect(status) {
+    return status === ReachabilityStatus.Broken;
+}
+/**
+ * Sweep `hrefs`, probing each unique in-scope URL exactly once.
+ *
+ * Results are sorted by URL so a sweep produces a stable, diffable report
+ * regardless of the order links appeared on the page.
+ */
+export function sweepLinks(hrefs, options) {
+    const { base, probe, allowExternal = [] } = options;
+    const baseHost = new URL(base).hostname;
+    // Dedup by normalized URL: a nav link repeated on every page is one check,
+    // and one dangling route should be reported once, not once per referrer.
+    const unique = new Map();
+    for (const href of hrefs) {
+        const link = normalizeLink(href, base);
+        if (link !== null && !unique.has(link.url))
+            unique.set(link.url, link);
+    }
+    const results = [];
+    for (const { link, scoped } of planSweep(hrefs, base, allowExternal)) {
+        results.push(scoped ? resolveOutcome(link, probe(link.url)) : skippedResult(link));
+    }
+    return { results, summary: summarize(results) };
+}
+/**
+ * Normalize, dedup, sort, and scope `hrefs` — everything the sync and async
+ * drivers must agree on. Shared so the two can never drift apart on which
+ * links get probed or in what order.
+ *
+ * Dedup by normalized URL: a nav link repeated on every page is one check, and
+ * one dangling route should be reported once, not once per referrer. Sorted by
+ * URL so a sweep produces a stable, diffable report regardless of the order
+ * links appeared on the page.
+ */
+function planSweep(hrefs, base, allowExternal) {
+    const baseHost = new URL(base).hostname;
+    const unique = new Map();
+    for (const href of hrefs) {
+        const link = normalizeLink(href, base);
+        if (link !== null && !unique.has(link.url))
+            unique.set(link.url, link);
+    }
+    return [...unique.values()]
+        .sort((a, b) => a.url.localeCompare(b.url))
+        .map((link) => ({
+        link,
+        scoped: inScope(link, baseHost, [...allowExternal]),
+    }));
+}
+function skippedResult(link) {
+    return {
+        url: link.url,
+        status: ReachabilityStatus.SkippedExternal,
+        httpStatus: null,
+        detail: 'off-site and not allowlisted',
+    };
+}
+/** Turn a probe outcome into a verdict, keeping dead and slow apart. */
+function resolveOutcome(link, outcome) {
+    if (outcome.kind === 'failed') {
+        return {
+            url: link.url,
+            status: ReachabilityStatus.Unreachable,
+            httpStatus: null,
+            // The reason is carried verbatim: an inconclusive result is only
+            // actionable if the reader can see WHY no verdict was reached.
+            detail: `no response (${outcome.reason})`,
+        };
+    }
+    return {
+        url: link.url,
+        status: classifyStatus(outcome.status),
+        httpStatus: outcome.status,
+        detail: `HTTP ${outcome.status}`,
+    };
+}
+/**
+ * {@link sweepLinks} over an async transport — the shape real network use takes.
+ *
+ * Probes sequentially on purpose. A sweep enumerates *every* link on a surface,
+ * so firing them concurrently at one host is indistinguishable from a small
+ * load test and invites the rate limiting that would then be misreported as
+ * `unreachable`. A slow, correct sweep beats a fast, self-poisoning one.
+ */
+export async function sweepLinksAsync(hrefs, options) {
+    const { base, probe, allowExternal = [] } = options;
+    const results = [];
+    for (const { link, scoped } of planSweep(hrefs, base, allowExternal)) {
+        results.push(scoped
+            ? resolveOutcome(link, await probe(link.url))
+            : skippedResult(link));
+    }
+    return { results, summary: summarize(results) };
+}
+/**
+ * A `fetch`-backed {@link AsyncLinkProbe} that keeps dead and slow apart.
+ *
+ * Any outcome where the server answered — including a 404 — is a `status`. Any
+ * outcome where no response arrived (timeout, DNS failure, refused connection)
+ * is a `failed`, carrying its reason. Callers should use this rather than
+ * hand-rolling a probe: deciding what counts as "no response" IS the guarantee
+ * this module exists to provide, and re-implementing it per caller is how the
+ * distinction gets quietly lost.
+ *
+ * Uses `HEAD`, falling back to `GET` when a server rejects `HEAD` outright
+ * (405/501) — some servers do, and treating that as a broken link would be a
+ * false positive.
+ */
+export function createHttpProbe(options = {}) {
+    const { timeoutMs = 10_000, fetchImpl = fetch } = options;
+    return async (url) => {
+        const attempt = async (method) => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const res = await fetchImpl(url, {
+                    method,
+                    redirect: 'follow',
+                    signal: controller.signal,
+                });
+                return { kind: 'status', status: res.status };
+            }
+            catch (err) {
+                const reason = controller.signal.aborted
+                    ? `timeout after ${timeoutMs}ms`
+                    : err instanceof Error
+                        ? err.message
+                        : String(err);
+                return { kind: 'failed', reason };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        const head = await attempt('HEAD');
+        if (head.kind === 'status' &&
+            (head.status === 405 || head.status === 501)) {
+            return attempt('GET');
+        }
+        return head;
+    };
+}
+function summarize(results) {
+    const summary = {
+        total: results.length,
+        ok: 0,
+        broken: 0,
+        unreachable: 0,
+        skipped: 0,
+        defects: 0,
+    };
+    for (const r of results) {
+        switch (r.status) {
+            case ReachabilityStatus.Broken:
+                summary.broken += 1;
+                break;
+            case ReachabilityStatus.Unreachable:
+                summary.unreachable += 1;
+                break;
+            case ReachabilityStatus.SkippedExternal:
+                summary.skipped += 1;
+                break;
+            // A 5xx is counted with `ok` for the accounting identity (it is not a
+            // link defect); it stays distinguishable via each result's own status.
+            default:
+                summary.ok += 1;
+        }
+        if (isDefect(r.status))
+            summary.defects += 1;
+    }
+    return summary;
+}
+//# sourceMappingURL=reachability.js.map

package/dist/engine/cli-commands.js

@@ -344,6 +344,7 @@ export function migrateCmd(opts, deps) {
             dryRun,
             framework: opts.framework || null,
             overlayPath,
+            force: opts.force ?? false,
         });
     }
     catch (e) {
@@ -367,6 +368,7 @@ export function migrateCmd(opts, deps) {
                 status: r.status,
                 note: r.note,
             })),
+            installed_workflows: report.installed_workflows.map((r) => r.to_dict()),
         }));
         return;
     }

package/dist/engine/cli.core.js

@@ -107,6 +107,7 @@ export function createCanaryCommand(depsInit = {}) {
         .option('-o, --overlay <path>', '[deprecated: use --from] Path to an overlay repo whose .canary/skills/ are deployed.')
         .option('--apply', 'Write files. Without this flag the command is a dry run.')
         .option('--check', 'Freshness gate: report drift without writing.')
+        .option('--force', 'Overwrite a .github/workflows/ file that differs from the overlay template. Without this flag a difference is only reported -- your CI is never rewritten behind your back.')
         .option('--json', 'Emit the report as JSON.')
         .action((opts) => {
         migrateCmd(opts, deps);

package/dist/engine/core/company-knowledge.js

@@ -13,9 +13,11 @@
  *   2. .canary/company.json            -- project-local config
  *   3. .canary/company.<env>.json      -- environment override (CANARY_ENV or explicit)
  *
- * List fields are unioned across sources; scalar fields (dashboard_url,
- * dashboard_token_env, notes) are replaced by the highest-priority source that
- * sets them.
+ * List fields ({@link _LIST_FIELDS}) are unioned across sources; scalar fields
+ * ({@link _SCALAR_FIELDS}) are replaced by the highest-priority source that
+ * sets a non-empty value. Those two arrays are the single place a new field
+ * opts into a merge rule, and both are checked for exhaustiveness at compile
+ * time.
  *
  * Python->TS nuances:
  *   - Python patches `Path.home()` in its tests to isolate the home tier. There
@@ -112,6 +114,18 @@ const _KNOWN_KEYS = new Set([
     'otel_exporter_endpoint',
     'notes',
     'brand',
+    // #459: read by the migrator (`_detectFramework` / overlay `deploy_to`
+    // matching) to decide which overlay skills deploy. It is NOT parsed into a
+    // `CompanyKnowledge` field, but it is emphatically not "ignored" either --
+    // warning that it is told anyone adopting an overlay that the single field
+    // driving their adoption does nothing.
+    'canary_shape',
+    // #459: repo-relative pointers a generated workflow interpolates (the
+    // coverage report the guardian reads; the controllers dir it scopes SUT
+    // analysis to). See `validateRepoRelativePath` for why they are validated
+    // rather than stored verbatim.
+    'coverage_report_path',
+    'sut_controllers_path',
 ]);
 const _HEX_COLOR_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
 const _BRAND_TEXT_MAX = 200;
@@ -234,6 +248,50 @@ function validateOtelEndpoint(raw, fieldName, warnings) {
     }
     return raw;
 }
+// A path that is absolute in any flavour git checkouts run under: POSIX
+// (`/x`), UNC / Windows-separator (`\x`), or drive-qualified (`C:x`, `C:/x`).
+// Drive-relative `C:x` is included deliberately -- it is not repo-relative.
+const _ABSOLUTE_PATH_RE = /^(?:[/\\]|[A-Za-z]:)/;
+// Newlines would break out of the scalar these values are interpolated into
+// when a workflow template is generated, so they are refused outright rather
+// than escaped -- no legitimate repo path contains one.
+const _PATH_CONTROL_RE = /[\r\n\t\0]/;
+/**
+ * A repo-relative path pointer (#459: `coverage_report_path`,
+ * `sut_controllers_path`).
+ *
+ * These are interpolated into generated GitHub Actions YAML, so validation is
+ * a safety boundary, not tidiness: an absolute path aims the generated CI at
+ * something outside the checkout, and a `..` segment escapes the repo. Both are
+ * dropped with a warning (the module's degrade-never-throw convention); a
+ * secret-like value raises so the whole layer is refused, exactly as every
+ * other non-notes field does.
+ *
+ * `..` is rejected as a SUBSTRING, not just as a path component. A component
+ * check would have to agree with the separator handling of whatever consumes
+ * the value later (shell, Actions expression, node `path`); refusing the two
+ * characters outright cannot disagree with anything. The cost is rejecting the
+ * vanishingly rare legitimate `report..xml`.
+ */
+function validateRepoRelativePath(raw, fieldName, warnings) {
+    if (typeof raw !== 'string') {
+        warnings.push(`${fieldName}: expected string, got ${pyTypeName(raw)} ${EMDASH} skipped`);
+        return '';
+    }
+    const value = raw.trim();
+    if (!value)
+        return '';
+    if (looksLikeSecret(value))
+        throw new SecretDetected(fieldName, value);
+    if (_ABSOLUTE_PATH_RE.test(value) ||
+        value.includes('..') ||
+        _PATH_CONTROL_RE.test(value)) {
+        warnings.push(`${fieldName}: dropped invalid repo-relative path ${pyRepr(raw)} ` +
+            `${EMDASH} must stay inside the repo (no absolute path, no '..')`);
+        return '';
+    }
+    return value;
+}
 /** Accept #RGB / #RRGGBB (any case); drop anything else with a warning. */
 function validateHexColor(raw, fieldName, warnings) {
     if (typeof raw !== 'string' || !raw)
@@ -426,6 +484,14 @@ function parseLayer(data, source) {
     if (Object.prototype.hasOwnProperty.call(data, 'otel_exporter_endpoint')) {
         otel_exporter_endpoint = validateOtelEndpoint(data['otel_exporter_endpoint'], 'otel_exporter_endpoint', warns);
     }
+    let coverage_report_path = '';
+    if (Object.prototype.hasOwnProperty.call(data, 'coverage_report_path')) {
+        coverage_report_path = validateRepoRelativePath(data['coverage_report_path'], 'coverage_report_path', warns);
+    }
+    let sut_controllers_path = '';
+    if (Object.prototype.hasOwnProperty.call(data, 'sut_controllers_path')) {
+        sut_controllers_path = validateRepoRelativePath(data['sut_controllers_path'], 'sut_controllers_path', warns);
+    }
     let notes = '';
     if (Object.prototype.hasOwnProperty.call(data, 'notes')) {
         const rawNotes = data['notes'];
@@ -449,6 +515,8 @@ function parseLayer(data, source) {
         dashboard_url,
         dashboard_token_env,
         otel_exporter_endpoint,
+        coverage_report_path,
+        sut_controllers_path,
         notes,
         brand,
         warnings: warns,
@@ -503,51 +571,66 @@ function union(a, b) {
     }
     return out;
 }
+const _LIST_FIELDS = [
+    'confluence_spaces',
+    'jira_projects',
+    'internal_doc_urls',
+    'internal_domains',
+    'mcp_servers',
+    'claude_code_skills',
+];
+const _SCALAR_FIELDS = [
+    'dashboard_url',
+    'dashboard_token_env',
+    'otel_exporter_endpoint',
+    'coverage_report_path',
+    'sut_controllers_path',
+    'notes',
+];
+// Compile-time exhaustiveness: adding a field to `Layer`/`MergedFields` without
+// adding it to the matching array above fails the build here (the assertion
+// type collapses to `never`) rather than silently dropping the field at merge.
+const _LIST_FIELDS_EXHAUSTIVE = true;
+const _SCALAR_FIELDS_EXHAUSTIVE = true;
+void _LIST_FIELDS_EXHAUSTIVE;
+void _SCALAR_FIELDS_EXHAUSTIVE;
+function mergeListFields(layers) {
+    const out = {};
+    for (const field of _LIST_FIELDS) {
+        let merged = [];
+        for (const layer of layers)
+            merged = union(merged, layer[field]);
+        out[field] = merged;
+    }
+    return out;
+}
+function mergeScalarFields(layers) {
+    const out = {};
+    for (const field of _SCALAR_FIELDS) {
+        let merged = '';
+        // Highest-priority non-empty wins. A layer whose value was DROPPED as
+        // invalid contributes '' and therefore leaves the lower layer's valid value
+        // standing (degrade, never blank out) -- load-bearing, and pinned by tests.
+        for (const layer of layers)
+            if (layer[field])
+                merged = layer[field];
+        out[field] = merged;
+    }
+    return out;
+}
 function mergeLayers(layers) {
-    let confluence_spaces = [];
-    let jira_projects = [];
-    let internal_doc_urls = [];
-    let internal_domains = [];
-    let mcp_servers = [];
-    let claude_code_skills = [];
-    let dashboard_url = '';
-    let dashboard_token_env = '';
-    let otel_exporter_endpoint = '';
-    let notes = '';
-    const warns = [];
+    const warnings = [];
     const sources = [];
     for (const layer of layers) {
-        confluence_spaces = union(confluence_spaces, layer.confluence_spaces);
-        jira_projects = union(jira_projects, layer.jira_projects);
-        internal_doc_urls = union(internal_doc_urls, layer.internal_doc_urls);
-        internal_domains = union(internal_domains, layer.internal_domains);
-        mcp_servers = union(mcp_servers, layer.mcp_servers);
-        claude_code_skills = union(claude_code_skills, layer.claude_code_skills);
-        if (layer.dashboard_url)
-            dashboard_url = layer.dashboard_url;
-        if (layer.dashboard_token_env)
-            dashboard_token_env = layer.dashboard_token_env;
-        if (layer.otel_exporter_endpoint)
-            otel_exporter_endpoint = layer.otel_exporter_endpoint;
-        if (layer.notes)
-            notes = layer.notes;
-        warns.push(...layer.warnings);
+        warnings.push(...layer.warnings);
         if (layer.source)
             sources.push(layer.source);
     }
     return {
-        confluence_spaces,
-        jira_projects,
-        internal_doc_urls,
-        internal_domains,
-        mcp_servers,
-        claude_code_skills,
-        dashboard_url,
-        dashboard_token_env,
-        otel_exporter_endpoint,
-        notes,
+        ...mergeListFields(layers),
+        ...mergeScalarFields(layers),
         brand: mergeBrand(layers),
-        warnings: warns,
+        warnings,
         sources,
     };
 }
@@ -579,6 +662,10 @@ export class CompanyKnowledge {
     dashboard_url;
     dashboard_token_env;
     otel_exporter_endpoint;
+    /** Repo-relative path to the coverage report a generated workflow reads. */
+    coverage_report_path;
+    /** Repo-relative path to the SUT controllers dir analysis is scoped to. */
+    sut_controllers_path;
     notes;
     brand;
     warnings;
@@ -594,6 +681,8 @@ export class CompanyKnowledge {
         this.dashboard_url = init.dashboard_url ?? '';
         this.dashboard_token_env = init.dashboard_token_env ?? '';
         this.otel_exporter_endpoint = init.otel_exporter_endpoint ?? '';
+        this.coverage_report_path = init.coverage_report_path ?? '';
+        this.sut_controllers_path = init.sut_controllers_path ?? '';
         this.notes = init.notes ?? '';
         this.brand = init.brand ?? new Brand();
         this.warnings = init.warnings ?? [];
@@ -727,6 +816,8 @@ export class CompanyKnowledge {
             dashboard_url: this.dashboard_url,
             dashboard_token_env: this.dashboard_token_env,
             otel_exporter_endpoint: this.otel_exporter_endpoint,
+            coverage_report_path: this.coverage_report_path,
+            sut_controllers_path: this.sut_controllers_path,
             notes: this.notes,
             brand: this.brand.toDict(),
             sources: this.sources,