Skip to content

The design language that makes your AI harness better at design.

JavaScript
22.2 KB
Raw Blame
//! JS: lib/staleness.mjs (Tier 1)

use crate::artifact_schema::*;
use crate::context::{BriefSummary, Ctx, TargetCandidate};
use crate::jsp;
use crate::util::{exists, js_trim, mtime_ms, read_json};
use once_cell::sync::Lazy;
use regex::Regex;
use serde_json::{Map, Value};

#[derive(Debug, Clone, serde::Serialize, PartialEq)]
pub struct Finding {
    pub id: String,
    pub artifact: String,
    pub path: Option<String>,
    pub severity: &'static str,
    pub summary: String,
    pub fix: String,
}

impl Finding {
    pub fn to_value(&self) -> Value {
        let mut m = Map::new();
        m.insert("id".into(), Value::String(self.id.clone()));
        m.insert("artifact".into(), Value::String(self.artifact.clone()));
        m.insert("path".into(), self.path.clone().map(Value::String).unwrap_or(Value::Null));
        m.insert("severity".into(), Value::String(self.severity.to_string()));
        m.insert("summary".into(), Value::String(self.summary.clone()));
        m.insert("fix".into(), Value::String(self.fix.clone()));
        Value::Object(m)
    }
}

pub fn finding(id: &str, artifact: &str, path: Option<String>, severity: &'static str, summary: String, fix: String) -> Finding {
    Finding { id: id.to_string(), artifact: artifact.to_string(), path, severity, summary, fix }
}

const KNOWN_CONFIG_KEYS: [&str; 10] =
    ["hook", "detector", "updateCheck", "stalenessCheck", "projectRoots", "buildPath", "browser", "telemetry", "$schema", "version"];
const BUILD_PATH_VALUES: [&str; 2] = ["comp", "code"];
const DIRECTION_WORK_PATHS: [&str; 2] = [".impeccable/surfaces", ".impeccable/mocks/decision"];
const KNOWN_DETECTOR_KEYS: [&str; 5] = ["ignoreRules", "ignoreFiles", "ignoreValues", "designSystem", "extensions"];

struct NativeEvidence {
    platform: &'static str,
    reason: &'static str,
}
const NATIVE_EVIDENCE_PATHS: [(&str, &str, &str); 5] = [
    ("pubspec.yaml", "adaptive", "a Flutter pubspec.yaml"),
    ("ios/Podfile", "ios", "an ios/Podfile"),
    ("android/build.gradle", "android", "an android/build.gradle"),
    ("android/build.gradle.kts", "android", "an android/build.gradle.kts"),
    ("ios/Runner.xcodeproj", "ios", "an ios/Runner.xcodeproj"),
];
const NATIVE_EVIDENCE_DEPENDENCIES: [(&str, &str, &str); 3] = [
    ("react-native", "adaptive", "a react-native dependency"),
    ("expo", "adaptive", "an expo dependency"),
    ("@react-native/metro-config", "adaptive", "a React Native metro config dependency"),
];

/// JS: designSidecarCandidatesFor(projectRoot, contextDir)
pub fn design_sidecar_candidates_for(project_root: &str, context_dir: Option<&str>) -> Vec<String> {
    let mut c = vec![jsp::join(&[project_root, ".impeccable", "design.json"]), jsp::join(&[project_root, "DESIGN.json"])];
    let ctx_legacy = jsp::join(&[context_dir.unwrap_or(project_root), "DESIGN.json"]);
    if !c.contains(&ctx_legacy) {
        c.push(ctx_legacy);
    }
    c
}

fn has_section(markdown: &str, heading: &str) -> bool {
    Regex::new(&format!(r"(?im)^##\s+{}\s*$", regex::escape(heading))).map(|r| r.is_match(markdown)).unwrap_or(false)
}

pub fn to_relative(file_path: Option<&str>, root: &str) -> Option<String> {
    let fp = file_path?;
    let rel = jsp::relative("/", root, fp);
    if !rel.is_empty() && !rel.starts_with("..") && !jsp::is_absolute(&rel) {
        Some(jsp::to_posix(&rel))
    } else {
        Some(fp.to_string())
    }
}

fn wrap_ticks(items: &[String]) -> String {
    items.iter().map(|k| format!("`{}`", k)).collect::<Vec<_>>().join(", ")
}

/// JS: checkProduct
pub fn check_product(product: Option<&str>, product_path: &str) -> Vec<Finding> {
    let Some(product) = product.filter(|p| !p.is_empty()) else { return vec![] };
    let mut out = Vec::new();
    for (heading, reason) in PRODUCT_DEPRECATED_SECTIONS {
        if !has_section(product, heading) {
            continue;
        }
        out.push(finding(
            &format!("product-deprecated-{}", heading.to_lowercase()),
            "PRODUCT.md",
            Some(product_path.to_string()),
            "mention",
            format!("PRODUCT.md still carries a `## {}` section. {}", heading, reason),
            format!(
                "Treat `## {}` as absent for every decision this session. Offer to delete the section; do not let its value influence the work either way.",
                heading
            ),
        ));
    }
    let stamped = read_product_schema_version(product);
    if stamped.is_none() && !PRODUCT_V4_SECTIONS.iter().any(|s| has_section(product, s)) {
        out.push(finding(
            "product-schema-legacy",
            "PRODUCT.md",
            Some(product_path.to_string()),
            "route",
            format!(
                "PRODUCT.md has no schema stamp and none of the sections the current record adds ({}), so it predates this version of the product record.",
                PRODUCT_V4_SECTIONS.join(", ")
            ),
            "Offer `init`, which preserves confirmed answers and fills the gaps by interview. Do not rewrite the file from inference.".to_string(),
        ));
    } else if let Some(v) = stamped {
        if v < PRODUCT_SCHEMA_VERSION {
            out.push(finding(
                "product-schema-outdated",
                "PRODUCT.md",
                Some(product_path.to_string()),
                "route",
                format!("PRODUCT.md is stamped product-schema {}; the current record is {}.", v, PRODUCT_SCHEMA_VERSION),
                "Offer `init` to bring the record current, preserving confirmed answers.".to_string(),
            ));
        }
    }
    out
}

/// JS: checkNativePlatformEvidence
pub fn check_native_platform_evidence(
    project_root: &str,
    platform: Option<&str>,
    product: Option<&str>,
    product_path: Option<&str>,
) -> Vec<Finding> {
    if project_root.is_empty() {
        return vec![];
    }
    if let Some(p) = platform {
        if !p.is_empty() && p != "web" {
            return vec![];
        }
    }
    let mut evidence: Vec<NativeEvidence> = Vec::new();
    for (rel, platform, reason) in NATIVE_EVIDENCE_PATHS {
        if exists(&jsp::join(&[project_root, rel])) {
            evidence.push(NativeEvidence { platform, reason });
        }
    }
    if let Some(pkg) = read_json(&jsp::join(&[project_root, "package.json"])) {
        // JS: { ...pkg.dependencies, ...pkg.devDependencies } then deps[name] truthy
        let dep_truthy = |name: &str| -> bool {
            let mut v: Option<&Value> = None;
            if let Some(d) = pkg.get("dependencies").and_then(|d| d.as_object()) {
                if let Some(x) = d.get(name) {
                    v = Some(x);
                }
            }
            if let Some(d) = pkg.get("devDependencies").and_then(|d| d.as_object()) {
                if let Some(x) = d.get(name) {
                    v = Some(x);
                }
            }
            match v {
                None => false,
                Some(x) => js_truthy(x),
            }
        };
        if pkg.is_object() || pkg.is_array() || (!pkg.is_null() && js_truthy(&pkg)) {
            for (name, platform, reason) in NATIVE_EVIDENCE_DEPENDENCIES {
                if dep_truthy(name) {
                    evidence.push(NativeEvidence { platform, reason });
                }
            }
        }
    }
    if evidence.is_empty() {
        return vec![];
    }
    let mut platforms: Vec<&str> = Vec::new();
    for e in &evidence {
        if !platforms.contains(&e.platform) {
            platforms.push(e.platform);
        }
    }
    let suggested = if platforms.len() > 1 || platforms.contains(&"adaptive") { "adaptive" } else { platforms[0] };
    let declared = if platform == Some("web") {
        "PRODUCT.md declares `## Platform: web`"
    } else if product.map(|p| !p.is_empty()).unwrap_or(false) {
        "PRODUCT.md has no `## Platform` section, so the project resolves to web"
    } else {
        "no PRODUCT.md declares a platform, so the project resolves to web"
    };
    vec![finding(
        "platform-native-evidence",
        "PRODUCT.md",
        product_path.map(|s| s.to_string()),
        "mention",
        format!(
            "{}, but the project carries {}. Web guidance is being applied to a native codebase, and the iOS and Android references never load.",
            declared,
            evidence.iter().map(|e| e.reason).collect::<Vec<_>>().join(" and ")
        ),
        format!(
            "Ask the user whether `## Platform` should be `{}`. If it should, write the value and load the matching native reference before designing.",
            suggested
        ),
    )]
}

pub fn js_truthy(v: &Value) -> bool {
    match v {
        Value::Null => false,
        Value::Bool(b) => *b,
        Value::Number(n) => n.as_f64().map(|f| f != 0.0 && !f.is_nan()).unwrap_or(true),
        Value::String(s) => !s.is_empty(),
        _ => true,
    }
}

/// JS: checkDesignSidecar
pub fn check_design_sidecar(design_path: Option<&str>, sidecar_candidates: &[String], project_root: &str) -> Vec<Finding> {
    let mut out = Vec::new();
    let canonical = sidecar_candidates.first();
    let Some(present) = sidecar_candidates.iter().find(|c| exists(c)) else { return out };
    let rel_present = to_relative(Some(present), project_root).unwrap();
    if let Some(canon) = canonical {
        if jsp::resolve(present, &[]) != jsp::resolve(canon, &[]) {
            out.push(finding(
                "design-sidecar-legacy-path",
                "design.json",
                Some(rel_present.clone()),
                "auto",
                format!("The design sidecar sits at {}, a location kept only for backward compatibility.", rel_present),
                format!(
                    "Move it to {} the next time the sidecar is written. No user decision is needed.",
                    to_relative(Some(canon), project_root).unwrap()
                ),
            ));
        }
    }
    let sidecar = read_json(present);
    let schema_version = read_sidecar_schema_version(sidecar.as_ref());
    if let Some(sc) = &sidecar {
        if js_truthy(sc) && (schema_version.is_none() || schema_version.unwrap() < DESIGN_SIDECAR_SCHEMA_VERSION) {
            out.push(finding(
                "design-sidecar-schema-outdated",
                "design.json",
                Some(rel_present.clone()),
                "route",
                format!(
                    "{} is schemaVersion {}; the current sidecar is {}. Token primitives moved to the DESIGN.md frontmatter, so the old shape carries values that are now read from two places.",
                    rel_present,
                    schema_version.map(|v| v.to_string()).unwrap_or_else(|| "unset".to_string()),
                    DESIGN_SIDECAR_SCHEMA_VERSION
                ),
                "Offer `document` to regenerate the sidecar. It reads the existing DESIGN.md, so no interview is needed.".to_string(),
            ));
        }
    }
    if let Some(dp) = design_path {
        let dm = mtime_ms(dp);
        let sm = mtime_ms(present);
        if let (Some(d), Some(s)) = (dm, sm) {
            if d > s {
                out.push(finding(
                    "design-sidecar-stale",
                    "design.json",
                    Some(rel_present.clone()),
                    "mention",
                    format!(
                        "DESIGN.md was edited after {} was generated, so the sidecar's ramps, shadows, motion tokens, and component snippets may contradict it.",
                        rel_present
                    ),
                    "Offer `document` to refresh the sidecar, preserving DESIGN.md.".to_string(),
                ));
            }
        }
    }
    out
}

pub fn unique_roots(a: &str, b: Option<&str>) -> Vec<String> {
    let mut roots = vec![jsp::resolve(a, &[])];
    if let Some(b) = b {
        if !b.is_empty() {
            let r = jsp::resolve(b, &[]);
            if !roots.contains(&r) {
                roots.push(r);
            }
        }
    }
    roots
}

/// JS: checkConfig
pub fn check_config(project_root: &str, repo_root: Option<&str>) -> Vec<Finding> {
    let mut out = Vec::new();
    for root in unique_roots(project_root, repo_root) {
        for name in ["config.json", "config.local.json"] {
            let fp = jsp::join(&[&root, ".impeccable", name]);
            let Some(raw) = read_json(&fp) else { continue };
            let Some(obj) = raw.as_object() else { continue };
            let rel = to_relative(Some(&fp), if project_root.is_empty() { &root } else { project_root }).unwrap();
            let unknown: Vec<String> = obj.keys().filter(|k| !KNOWN_CONFIG_KEYS.contains(&k.as_str())).cloned().collect();
            if !unknown.is_empty() {
                out.push(finding(
                    "config-unknown-keys",
                    "config.json",
                    Some(rel.clone()),
                    "mention",
                    format!(
                        "{} has top-level key(s) nothing reads: {}. Recognized keys are {}.",
                        rel,
                        wrap_ticks(&unknown),
                        wrap_ticks(&KNOWN_CONFIG_KEYS.iter().map(|s| s.to_string()).collect::<Vec<_>>())
                    ),
                    "Report the exact keys to the user. A near-miss of a real key is a setting that has never applied.".to_string(),
                ));
            }
            if let Some(bp) = obj.get("buildPath") {
                let ok = bp.as_str().map(|s| BUILD_PATH_VALUES.contains(&s)).unwrap_or(false);
                if !ok {
                    out.push(finding(
                        "config-invalid-build-path",
                        "config.json",
                        Some(rel.clone()),
                        "mention",
                        format!(
                            "{} sets `buildPath` to {}, which nothing reads. The values are {}.",
                            rel,
                            js_json_stringify(bp),
                            BUILD_PATH_VALUES.iter().map(|v| format!("`{}`", v)).collect::<Vec<_>>().join(" and ")
                        ),
                        "Report the value. An unread `buildPath` does not fall back to the other path; it falls back to the default, so a project meaning `code` has been building comp-led.".to_string(),
                    ));
                }
            }
            if let Some(det) = obj.get("detector").and_then(|d| d.as_object()) {
                let unknown_d: Vec<String> = det.keys().filter(|k| !KNOWN_DETECTOR_KEYS.contains(&k.as_str())).cloned().collect();
                if !unknown_d.is_empty() {
                    out.push(finding(
                        "config-unknown-detector-keys",
                        "config.json",
                        Some(rel.clone()),
                        "mention",
                        format!(
                            "{} has `detector` key(s) nothing reads: {}. Recognized keys are {}.",
                            rel,
                            wrap_ticks(&unknown_d),
                            wrap_ticks(&KNOWN_DETECTOR_KEYS.iter().map(|s| s.to_string()).collect::<Vec<_>>())
                        ),
                        "Report the exact keys. `ignoreRule` for `ignoreRules` is the common one, and it silences nothing.".to_string(),
                    ));
                }
            }
        }
    }
    out
}

/// `JSON.stringify(v)` for a single value (undefined -> "undefined" never occurs here since key present).
pub fn js_json_stringify(v: &Value) -> String {
    serde_json::to_string(v).unwrap_or_else(|_| "null".into())
}

/// JS: checkBuildPathUnset
pub fn check_build_path_unset(project_root: &str, repo_root: Option<&str>, product: Option<&str>) -> Vec<Finding> {
    if project_root.is_empty() || !product.map(|p| !p.is_empty()).unwrap_or(false) {
        return vec![];
    }
    for root in unique_roots(project_root, repo_root) {
        for name in ["config.json", "config.local.json"] {
            if let Some(raw) = read_json(&jsp::join(&[&root, ".impeccable", name])) {
                if js_truthy(&raw) && raw.as_object().map(|o| o.contains_key("buildPath")).unwrap_or(false) {
                    return vec![];
                }
            }
        }
    }
    let evidence: Vec<&str> = DIRECTION_WORK_PATHS.iter().copied().filter(|rel| exists(&jsp::join(&[project_root, rel]))).collect();
    if evidence.is_empty() {
        return vec![];
    }
    vec![finding(
        "config-build-path-unset",
        "config.json",
        Some(".impeccable/config.json".to_string()),
        "mention",
        "This project has run visual direction work but records no `buildPath`, so Persuade and Experience rounds take the comp-first default without anyone having chosen it.".to_string(),
        "Only when image generation exists in your tool surface, offer the choice once, saying it covers landing pages and showcase surfaces (app screens and documents build code-first either way): **comp-first** (an image sets the bar before any code; bolder composition, slower) or **code-first** (build directly; ambition carried by the direction contract; leaner, faster). Write the answer to `.impeccable/config.json` as `\"buildPath\": \"comp\"` or `\"buildPath\": \"code\"`, merging with the keys already there. Without image generation there is no choice to record: stay silent.".to_string(),
    )]
}

/// JS: checkSurfaceBriefs
pub fn check_surface_briefs(candidates: &[BriefSummary], project_root: &str) -> Vec<Finding> {
    if project_root.is_empty() {
        return vec![];
    }
    let mut orphaned: Vec<&BriefSummary> = Vec::new();
    for b in candidates {
        let Some(t) = b.primary_target.as_deref() else { continue };
        if t.is_empty() {
            continue;
        }
        let lower = t.to_ascii_lowercase();
        if lower.starts_with("http://") || lower.starts_with("https://") || t.starts_with("route:") {
            continue;
        }
        if !exists(&jsp::join(&[project_root, t])) {
            orphaned.push(b);
        }
    }
    if orphaned.is_empty() {
        return vec![];
    }
    let paths: Vec<String> = orphaned.iter().map(|b| b.path.clone()).filter(|p| !p.is_empty()).collect();
    vec![finding(
        "surface-brief-orphaned",
        "surface brief",
        if paths.is_empty() { None } else { Some(paths.join(", ")) },
        "mention",
        format!(
            "{} persisted surface brief(s) name a primary target that no longer exists: {}.",
            orphaned.len(),
            orphaned
                .iter()
                .map(|b| format!("{} → {}", b.path, b.primary_target.as_deref().unwrap_or("")))
                .collect::<Vec<_>>()
                .join("; ")
        ),
        "Ask whether the surface moved (repoint the brief) or was removed (delete the brief). Until then the brief is authority for a file that is gone.".to_string(),
    )]
}

/// JS: checkProjectRoots
pub fn check_project_roots(patterns: &[String], candidates_len: usize) -> Vec<Finding> {
    let positive: Vec<&String> = patterns.iter().filter(|p| !p.is_empty() && !js_trim(p).starts_with('!')).collect();
    if positive.is_empty() || candidates_len > 0 {
        return vec![];
    }
    vec![finding(
        "config-project-roots-match-nothing",
        "config.json",
        Some(".impeccable/config.json".to_string()),
        "mention",
        format!(
            "`projectRoots` declares {}, but no directory matches any of them, so the repo root is being treated as the active project.",
            positive.iter().map(|p| format!("`{}`", p)).collect::<Vec<_>>().join(", ")
        ),
        "Report the patterns and ask which directories they should name. A renamed workspace folder is the usual cause.".to_string(),
    )]
}

pub struct BootExtras {
    pub abs_design_path: Option<String>,
    pub sidecar_candidates: Vec<String>,
    pub project_root_patterns: Option<Vec<String>>,
    pub target_candidates: Vec<TargetCandidate>,
}

/// JS: collectBootFindingGroups(ctx, extras) — the boot artifact checks
/// grouped by artifact, so deeper reports (doctor) can interleave their own
/// checks without rebuilding this policy (upstream 80997663).
pub struct BootFindingGroups {
    pub product: Vec<Finding>,
    pub native_platform: Vec<Finding>,
    pub design_sidecar: Vec<Finding>,
    pub config: Vec<Finding>,
    pub build_path: Vec<Finding>,
    pub surface_briefs: Vec<Finding>,
    pub project_roots: Vec<Finding>,
}

pub fn collect_boot_finding_groups(ctx: &Ctx, cwd: &str, extras: &BootExtras) -> BootFindingGroups {
    let project_root = if ctx.project_root.is_empty() { cwd.to_string() } else { ctx.project_root.clone() };
    BootFindingGroups {
        product: check_product(ctx.product.as_deref(), ctx.product_path.as_deref().unwrap_or("PRODUCT.md")),
        // Only checked once a PRODUCT.md exists. Without one the boot already
        // emits NO_PRODUCT_MD and routes into init, which asks for the
        // platform directly; a second signal saying the same thing is noise.
        native_platform: if ctx.product.as_deref().map(|p| !p.is_empty()).unwrap_or(false) {
            check_native_platform_evidence(
                &project_root,
                ctx.platform.as_deref(),
                ctx.product.as_deref(),
                ctx.product_path.as_deref(),
            )
        } else {
            Vec::new()
        },
        design_sidecar: check_design_sidecar(extras.abs_design_path.as_deref(), &extras.sidecar_candidates, &project_root),
        config: check_config(&project_root, Some(&ctx.repo_root)),
        build_path: check_build_path_unset(&project_root, Some(&ctx.repo_root), ctx.product.as_deref()),
        surface_briefs: check_surface_briefs(&ctx.surface_brief_candidates, &project_root),
        project_roots: match &extras.project_root_patterns {
            Some(patterns) => check_project_roots(patterns, extras.target_candidates.len()),
            None => Vec::new(),
        },
    }
}

/// JS: collectBootFindings(ctx, extras)
pub fn collect_boot_findings(ctx: &Ctx, cwd: &str, extras: &BootExtras) -> Vec<Finding> {
    let groups = collect_boot_finding_groups(ctx, cwd, extras);
    let mut out = Vec::new();
    out.extend(groups.product);
    out.extend(groups.native_platform);
    out.extend(groups.design_sidecar);
    out.extend(groups.config);
    out.extend(groups.build_path);
    out.extend(groups.surface_briefs);
    out.extend(groups.project_roots);
    out
}

pub static _UNUSED: Lazy<()> = Lazy::new(|| ());