docs.cpp
impl/frontend/docs.cpp · 766 line(s) · c
// docs.cpp -- `sleela docs` subcommand implementation. See docs.h.
// ===========================================================================
#include "docs.h"
#include "library_index.h"
#include <algorithm>
#include <cctype>
#include <chrono>
#include <cstdint>
#include <cstdlib>
#include <filesystem>
#include <fstream>
#include <iostream>
#include <map>
#include <regex>
#include <sstream>
#include <string>
#include <vector>
namespace fs = std::filesystem;
namespace sleela {
namespace {
// ---- small text helpers ---------------------------------------------------
std::string lower(std::string s){ for(char& c:s) c=(char)std::tolower((unsigned char)c); return s; }
std::string trim(const std::string& s){
size_t a=s.find_first_not_of(" \t\r\n");
if(a==std::string::npos) return "";
size_t b=s.find_last_not_of(" \t\r\n");
return s.substr(a,b-a+1);
}
std::string squeeze(const std::string& s){ return std::regex_replace(trim(s), std::regex("\\s+"), " "); }
// A levenshtein-free "nearness": a topic is near a candidate when it is a
// case-insensitive substring of the candidate, or the candidate of it, or they
// share a long common prefix. Returns a score 0..100 (higher = closer); 0 = no.
int nearness(const std::string& topicL, const std::string& candL){
if(topicL==candL) return 100;
if(candL.find(topicL)!=std::string::npos) return 85; // topic inside candidate
if(topicL.find(candL)!=std::string::npos) return 75; // candidate inside topic
size_t n=std::min(topicL.size(),candL.size()), p=0;
while(p<n && topicL[p]==candL[p]) ++p;
if(p>=3) return (int)(40 + p); // shared prefix
return 0;
}
// ---- the parsed, rich doc model -------------------------------------------
struct Tag { std::string name, value; };
struct Member {
std::string kind, name, sig, desc;
std::vector<Tag> tags; // @param/@returns/... harvested above it
};
struct ClassDoc {
std::string kind, name, extends, summary;
std::vector<Member> fields, methods;
std::vector<Tag> tags; // class-level @intent/@thesis/@axiom/...
bool hasMetadata=false;
};
struct UnitDoc {
std::string package, name, path, definition, syntax;
std::vector<ClassDoc> classes;
};
bool isMetaName(const std::string& n){
static const std::regex r("^(metaVersion|metaId|metaAuthor|metaDate|metaCopyright|metaTrademark|"
"metaCorporation|metaOrigin|metaBirthDate|metaScienceRating|metaNationalSchedule)$");
static const std::regex a("^(get|set)(MetaVersion|MetaId|Author|Date|Copyright|Trademark|"
"Corporation|Origin|BirthDate|ScienceRating|NationalSchedule)$");
return std::regex_match(n,r) || std::regex_match(n,a);
}
// Pull the plain text out of a single comment line (`<`, `<<`/`>>`, `//`), or
// empty string when the line is a decorative rule, or a sentinel-only line.
std::string commentText(const std::string& raw){
std::string s=trim(raw);
if(s.rfind("<<",0)==0){ s=s.substr(2); if(s.size()>=2 && s.substr(s.size()-2)==">>") s=s.substr(0,s.size()-2); }
else if(!s.empty() && s[0]=='<' && s.rfind("<=",0)!=0){ s=s.substr(1); if(!s.empty() && s.back()=='>') s.pop_back(); }
else if(s.rfind("//",0)==0){ s=s.substr(2); }
else if(s.rfind("#",0)==0){ return ""; }
else { return ""; }
s=trim(s);
for(const char* sent : {"@doc","@page","@intent","@title"}) if(s.rfind(sent,0)==0) s=trim(s.substr(std::string(sent).size()));
bool rule=!s.empty(); for(char c:s) if(c!='-'&&c!=' '){ rule=false; break; }
if(rule) return "";
return s;
}
// Collect the raw comment lines (delimiters stripped) of the contiguous run
// ending at `end`, top-to-bottom. Used by both the plain-prose and the tagged
// gatherers so they agree on run boundaries.
std::vector<std::string> gatherRaw(const std::vector<std::string>& lines, int end){
std::vector<std::string> pieces; int i=end;
while(i>=0){
std::string s=trim(lines[i]);
if(s.empty()) break;
bool isComment = (!s.empty() && (s[0]=='<' || s.rfind("//",0)==0 || s.rfind("<<",0)==0));
if(!isComment){
if(!pieces.empty() && s.find(';')==std::string::npos && s.find('{')==std::string::npos && s.find('(')==std::string::npos){ pieces.push_back(s); --i; continue; }
break;
}
// keep the raw (post-delimiter) text, preserving a leading @tag token
std::string t=trim(lines[i]);
if(t.rfind("<<",0)==0){ t=t.substr(2); if(t.size()>=2 && t.substr(t.size()-2)==">>") t=t.substr(0,t.size()-2); }
else if(!t.empty() && t[0]=='<'){ t=t.substr(1); if(!t.empty() && t.back()=='>') t.pop_back(); }
else if(t.rfind("//",0)==0){ t=t.substr(2); }
pieces.push_back(trim(t)); --i;
}
std::reverse(pieces.begin(),pieces.end());
return pieces;
}
// Split a comment run into (free prose, tags). A line whose first token is an
// @word starts a tag; following non-@ lines continue that tag's value; lines
// before any @tag are summary prose. Recognised SleelaDoc tags only.
void splitDoc(const std::vector<std::string>& raw, std::string& proseOut, std::vector<Tag>& tagsOut){
static const std::regex tagHead("^@([A-Za-z]+)\\b\\s*(.*)$");
std::vector<std::string> prose; Tag* curTag=nullptr;
for(auto line : raw){
std::string s=trim(line);
bool rule=!s.empty(); for(char c:s) if(c!='-'&&c!=' '){ rule=false; break; }
if(rule||s.empty()) continue;
std::smatch m;
if(std::regex_match(s,m,tagHead)){
tagsOut.push_back(Tag{lower(m[1].str()), trim(m[2].str())});
curTag=&tagsOut.back();
} else if(curTag){
if(!curTag->value.empty()) curTag->value+=" ";
curTag->value+=s;
} else {
prose.push_back(s);
}
}
std::string p; for(auto& x:prose){ if(x.empty()) continue; if(!p.empty()) p+=" "; p+=x; }
proseOut=squeeze(p);
}
// Gather the contiguous comment run that ends at line index `end` (inclusive),
// walking upward, and join it as one prose string.
std::string gatherAbove(const std::vector<std::string>& lines, int end){
std::vector<std::string> pieces; int i=end;
while(i>=0){
std::string s=trim(lines[i]);
if(s.empty()) break;
std::string t=commentText(lines[i]);
bool isComment = (!s.empty() && (s[0]=='<' || s.rfind("//",0)==0 || s.rfind("<<",0)==0));
if(!isComment){
// allow interior lines of a << >> block (no delimiter) only mid-run
if(!pieces.empty() && s.find(';')==std::string::npos && s.find('{')==std::string::npos && s.find('(')==std::string::npos){ pieces.push_back(s); --i; continue; }
break;
}
pieces.push_back(t); --i;
}
std::reverse(pieces.begin(),pieces.end());
std::string out; for(const auto& p:pieces){ if(p.empty()) continue; if(!out.empty()) out+=" "; out+=p; }
return squeeze(out);
}
// Parse one .sleela unit into a rich doc model (mirrors the Python generator's
// grammar closely enough for the terminal rendering). Symbol paths are stored
// RELATIVE to the index root, so resolve against it before opening.
UnitDoc parseUnit(const library::Symbol& sym, const std::string& libRoot){
UnitDoc u; u.package=sym.package; u.name=sym.name;
fs::path full = fs::path(sym.path).is_absolute() ? fs::path(sym.path) : (fs::path(libRoot)/sym.path);
// Display a stable, repo-relative path (lib/<...>), not an absolute build
// path, so a page is identical on every machine and clean inside the JAR.
fs::path libp(libRoot);
std::string libName = libp.filename().string().empty()? "lib" : libp.filename().string();
u.path = (fs::path(libName)/sym.path).generic_string();
std::ifstream in(full); if(!in) return u;
std::stringstream ss; ss<<in.rdbuf(); std::string text=ss.str();
// header Definition line (within the first block)
std::smatch m; std::string head=text.substr(0,std::min<size_t>(text.size(),1600));
if(std::regex_search(head,m,std::regex("Definition:\\s*([^>]+)"))) u.definition=squeeze(m[1].str());
if(std::regex_search(text,m,std::regex("#sleela\\s+([0-9.]+)"))) u.syntax=m[1].str();
std::vector<std::string> lines; { std::stringstream ls(text); std::string ln; while(std::getline(ls,ln)) lines.push_back(ln); }
static const std::regex classRe("^(class|struct|interface)\\s+([A-Za-z_][A-Za-z0-9_]*)(?:\\s+extends\\s+([A-Za-z_][A-Za-z0-9_]*))?");
static const std::regex fieldRe("^(?:static\\s+)?(?:final\\s+)?([A-Za-z_][A-Za-z0-9_]*(?:\\s*\\[\\s*\\])?)\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*(?:=.*)?;\\s*$");
static const std::regex methRe("^(?:static\\s+)?(?:final\\s+)?([A-Za-z_][A-Za-z0-9_]*(?:\\s*\\[\\s*\\])?)\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*\\(");
ClassDoc* cur=nullptr; bool inBlock=false; int depth=0;
for(int idx=0;idx<(int)lines.size();++idx){
std::string s=trim(lines[idx]);
if(inBlock){ if(s.find(">>")!=std::string::npos) inBlock=false; continue; }
if(s.rfind("<<",0)==0 && s.find(">>")==std::string::npos){ inBlock=true; continue; }
if(!s.empty() && (s[0]=='<' || s.rfind("//",0)==0)) continue;
if(s.rfind("#",0)==0) continue;
int opens=(int)std::count(s.begin(),s.end(),'{');
int closes=(int)std::count(s.begin(),s.end(),'}');
std::smatch cm;
if(std::regex_search(s,cm,classRe)){
u.classes.push_back(ClassDoc{cm[1].str(),cm[2].str(),cm[3].matched?cm[3].str():"", "", {}, {}, {}, false});
cur=&u.classes.back();
{ std::string prose; std::vector<Tag> tg; splitDoc(gatherRaw(lines,idx-1),prose,tg); cur->summary=prose; cur->tags=tg; }
depth += opens-closes; // usually enters the class body (depth 1)
continue;
}
if(!cur){ depth += opens-closes; continue; }
// Members live at the class-body level (depth==1). Deeper lines are
// method-body locals (int i = 0; return this; ...) and must be skipped.
bool atClassBody = (depth==1);
std::smatch mm;
if(atClassBody && std::regex_search(s,mm,fieldRe)){
std::string nm=mm[2].str();
if(isMetaName(nm)){ cur->hasMetadata=true; }
else { std::string prose; std::vector<Tag> tg; splitDoc(gatherRaw(lines,idx-1),prose,tg);
cur->fields.push_back(Member{"field",nm,squeeze(s.substr(0,s.size()-1)),prose,tg}); }
} else if(atClassBody && std::regex_search(s,mm,methRe)){
std::string nm=mm[2].str();
if(isMetaName(nm)){ cur->hasMetadata=true; }
else { std::string sig=s; size_t br=sig.find('{'); if(br!=std::string::npos) sig=trim(sig.substr(0,br));
std::string prose; std::vector<Tag> tg; splitDoc(gatherRaw(lines,idx-1),prose,tg);
cur->methods.push_back(Member{"method",nm,squeeze(sig),prose,tg}); }
}
depth += opens-closes;
if(depth<0) depth=0;
}
return u;
}
// ---- rendering -------------------------------------------------------------
void rule(std::ostream& o,char c='='){ o<<std::string(74,c)<<"\n"; }
void renderClass(std::ostream& o, const UnitDoc& u, const ClassDoc& c){
rule(o);
o<<" "<<c.kind<<" "<<c.name;
if(!c.extends.empty()) o<<" (extends "<<c.extends<<")";
o<<"\n";
o<<" package "<<u.package<<" | source "<<u.path;
if(!u.syntax.empty()) o<<" | #sleela "<<u.syntax;
o<<"\n";
rule(o);
// helper: first tag value matching any of the given names (class scope)
auto classTag=[&](std::initializer_list<const char*> names)->std::string{
for(const char* nm:names) for(const auto& t:c.tags) if(t.name==nm) return t.value; return std::string(); };
auto allTags=[&](const char* name)->std::vector<std::string>{
std::vector<std::string> v; for(const auto& t:c.tags) if(t.name==name) v.push_back(t.value); return v; };
if(!u.definition.empty()){ o<<"\nDEFINITION\n "<<u.definition<<"\n"; }
// DESIGN PURPOSE: prefer an explicit @intent, then @thesis, then the
// harvested summary prose. Richer when the author tagged intent.
std::string intent=classTag({"intent"});
std::string thesis=classTag({"thesis"});
o<<"\nDESIGN PURPOSE\n";
if(!intent.empty()) o<<" "<<intent<<"\n";
if(!c.summary.empty() && c.summary!=intent) o<<" "<<c.summary<<"\n";
if(!thesis.empty()) o<<" Thesis: "<<thesis<<"\n";
if(intent.empty() && c.summary.empty() && thesis.empty()) o<<" (no stated purpose; see the source header)\n";
// Axioms / invariants: the load-bearing promises, when the author stated them.
{ auto ax=allTags("axiom"); auto inv=allTags("invariant");
if(!ax.empty()||!inv.empty()){
o<<"\nPRINCIPLES\n";
for(auto& a:ax) o<<" * axiom: "<<a<<"\n";
for(auto& i:inv) o<<" * invariant: "<<i<<"\n";
} }
// RELATIONSHIPS: what it builds on, author @see links, and the member tally.
o<<"\nRELATIONSHIPS\n";
if(!c.extends.empty()) o<<" * builds on: "<<c.extends<<"\n";
for(auto& s:allTags("see")) o<<" * see also: "<<s<<"\n";
o<<" * fields: "<<c.fields.size()<<" methods: "<<c.methods.size()<<"\n";
if(c.hasMetadata) o<<" * carries the standard Metadata Class record (provenance + fiduciary attributes)\n";
// STRUCTURE: the members, each with its harvested explanation.
if(!c.fields.empty()){
o<<"\nSTRUCTURE -- state\n";
for(const auto& f:c.fields){ o<<" "<<f.sig<<"\n"; if(!f.desc.empty()) o<<" "<<f.desc<<"\n"; }
}
if(!c.methods.empty()){
o<<"\nSTRUCTURE -- behaviour\n";
for(const auto& mth:c.methods){
o<<" "<<mth.sig<<"\n";
if(!mth.desc.empty()) o<<" "<<mth.desc<<"\n";
for(const auto& t:mth.tags){
if(t.name=="param") o<<" param "<<t.value<<"\n";
else if(t.name=="returns"||t.name=="return") o<<" returns "<<t.value<<"\n";
else if(t.name=="throws") o<<" throws "<<t.value<<"\n";
}
}
}
// USER CLAYS: the usage habits a reader brings, and the cues that make a
// present audience read more carefully. Derived, not invented: it names the
// assumption a reader trained on other systems will carry in, and points at
// the careful cue (the class's own stated purpose / metadata).
o<<"\nUSER CLAYS\n";
o<<" * Assumed Be: a reader trained on other peoples' systems will reach for\n"
" "<<c.name<<" expecting the familiar shape of its name; read the DESIGN\n"
" PURPOSE before assuming behaviour by analogy.\n";
std::string cue = !intent.empty()? intent : c.summary;
o<<" * Careful cue: "<<(cue.empty()? std::string("consult the source header and the member explanations above")
: squeeze(cue).substr(0,std::min<size_t>(cue.size(),180)))<<"\n";
o<<" * Audience: INT (the attentive reader) studies the RELATIONSHIPS;\n"
" Swarmy (the habitual reader) should slow at the Careful cue.\n";
// MASTERY LEVELS: a graduated study ladder over this class. Author-supplied
// @mastery lines (if any) are listed first as the class's own guidance; the
// standard five-rung ladder always follows so every page teaches the method.
o<<"\nMASTERY LEVELS\n";
{ auto ms=allTags("mastery"); for(size_t k=0;k<ms.size();++k) o<<" * "<<ms[k]<<"\n"; if(!ms.empty()) o<<" --\n"; }
o<<" 1 Recognise -- name "<<c.name<<" and say, in one line, what it is for.\n";
o<<" 2 Use -- call its "<<c.methods.size()<<" method(s) for the common task.\n";
o<<" 3 Relate -- place it among its collaborators"<<(c.extends.empty()?"":" and its base "+c.extends)<<".\n";
o<<" 4 Extend -- change or specialise its behaviour without breaking callers.\n";
o<<" 5 Teach -- explain its design purpose to the next student.\n";
o<<"\n";
}
void renderPackage(std::ostream& o, const library::Index& ix, const std::string& pkg){
rule(o);
o<<" package "<<pkg<<"\n";
rule(o);
std::vector<const library::Symbol*> units;
for(const auto& s:ix.symbols()) if(s.package==pkg) units.push_back(&s);
std::sort(units.begin(),units.end(),[](auto*a,auto*b){return a->name<b->name;});
o<<"\n"<<units.size()<<" documentable unit(s) in package '"<<pkg<<"':\n\n";
for(auto* s:units){
UnitDoc u=parseUnit(*s,ix.root());
std::string one = !u.definition.empty()? u.definition
: (!u.classes.empty() && !u.classes.front().summary.empty()? u.classes.front().summary : std::string());
if(one.size()>96) one=one.substr(0,93)+"...";
o<<" "<<s->name;
if(!one.empty()) o<<"\n "<<one;
o<<"\n";
}
// Facade-only hint: a package whose only /lib unit is the SLPackage marker
// has its real material elsewhere on disk. Offer the live OS search.
bool facadeOnly = (units.size()==1 && units.front()->name=="SLPackage");
if(facadeOnly){
o<<"\nThis is a FACADE package: its /lib entry is only the package marker.\n"
<<"Find and document its real files on disk with the live OS search:\n"
<<" sleela docs --facade "<<pkg<<"\n"
<<"(bounded by 6 MB / 6000 files / 6 min; widen with --facade-root <dir>)\n\n";
} else {
o<<"\nRead one in full with: sleela docs "<<pkg<<" <ClassName>\n"
<<" or: sleela docs <ClassName>\n\n";
}
}
void listAll(std::ostream& o, const library::Index& ix){
std::map<std::string,int> pkgCount;
for(const auto& s:ix.symbols()) ++pkgCount[s.package];
rule(o);
o<<" SleelaDoc -- all documentable topics\n";
rule(o);
o<<"\n"<<pkgCount.size()<<" package(s), "<<ix.symbolCount()<<" unit(s). Ask for any by name:\n\n";
o<<" sleela docs <package> e.g. sleela docs crypto\n";
o<<" sleela docs <ClassName> e.g. sleela docs stringbuilder\n";
o<<" sleela docs <package> <Class> the exact unit\n\n";
o<<"PACKAGES\n";
for(const auto& kv:pkgCount){ if(kv.first=="__root__") continue; o<<" "<<kv.first<<" ("<<kv.second<<")\n"; }
o<<"\n";
}
void suggestNear(std::ostream& o, const library::Index& ix, const std::string& topic){
std::string tL=lower(topic);
struct Hit{ int score; std::string pkg,name; };
std::vector<Hit> hits;
std::map<std::string,int> pkgSeen;
for(const auto& s:ix.symbols()){
int sc=nearness(tL,lower(s.name));
if(sc>0) hits.push_back({sc,s.package,s.name});
int pc=nearness(tL,lower(s.package));
if(pc>0 && !pkgSeen[s.package]++) hits.push_back({pc-1,s.package,"(whole package)"});
}
std::sort(hits.begin(),hits.end(),[](const Hit&a,const Hit&b){return a.score>b.score;});
o<<"No exact topic '"<<topic<<"'. Near results:\n\n";
int shown=0;
for(const auto& h:hits){ if(shown++>=12) break; o<<" "<<h.pkg<<" "<<h.name<<"\n"; }
if(shown==0) o<<" (nothing close -- try 'sleela docs' for the full list)\n";
o<<"\n";
}
// ---- pre-generated corpus (deliverable #4) --------------------------------
// The CLI prefers a pre-generated plain-text corpus when present: it is fast,
// offline, and ships inside the SleelaDoc JAR alongside sources (deliverable
// #5). Layout, rooted at the SleelaDoc root (api/sleela/docs by default):
// <root>/TOPICS.index one "package<TAB>Unit" line per unit
// <root>/<package>/<Unit>.txt the rendered class page
// <root>/<package>/_package.txt the rendered package overview
// The corpus is always byte-identical to live output because both go through
// the same renderClass/renderPackage writers.
// Where the corpus lives. Overridable with SLEELA_DOCS_DIR; else <root>/api/
// sleela/docs under the discovered /lib root's parent (the repo/install root).
std::string corpusDir(const library::Index& ix){
if(const char* e=std::getenv("SLEELA_DOCS_DIR"); e&&*e) return e;
fs::path lib(ix.root());
fs::path base = lib.has_parent_path()? lib.parent_path() : lib; // repo/install root
return (base/"api"/"sleela"/"docs").generic_string();
}
// Emit one cached page if it exists; returns true when served from cache.
bool serveCached(std::ostream& o, const std::string& dir, const std::string& pkg, const std::string& unit){
fs::path p = fs::path(dir)/pkg/(unit+".txt");
std::ifstream in(p); if(!in) return false;
o<<in.rdbuf();
return true;
}
// Packages excluded from the COMMITTED corpus (and the JAR). The java compat
// mirror and the early-access trees are enormous (the java package alone is
// ~5k units / 22 MB) and are faithful re-declarations of upstream Java, not
// SLeeLa standard-library design. The live `sleela docs java ...` path still
// documents them on demand; only the pre-generated corpus is scoped to the
// SLeeLa standard library. Override by setting SLEELA_DOCS_ALL=1.
bool corpusIncludes(const std::string& pkg){
if(const char* e=std::getenv("SLEELA_DOCS_ALL"); e&&*e&&std::string(e)!="0") return true;
if(pkg=="__root__") return false;
if(pkg=="java") return false;
return true;
}
// Generate the entire corpus under `outDir`. Returns 0 on success.
int generateCorpus(const library::Index& ix, const std::string& outDir){
std::error_code ec;
fs::create_directories(outDir,ec);
std::ofstream index((fs::path(outDir)/"TOPICS.index").string());
if(!index){ std::cerr<<"sleela docs --generate: cannot write under "<<outDir<<"\n"; return 1; }
// Collect packages in sorted order for stable, reviewable output.
std::map<std::string,std::vector<const library::Symbol*>> byPkg;
for(const auto& s:ix.symbols()){
if(s.path.find("early_access")!=std::string::npos) continue;
if(!corpusIncludes(s.package)) continue;
byPkg[s.package].push_back(&s);
}
size_t units=0, pages=0;
for(auto& kv:byPkg){
const std::string& pkg=kv.first;
if(pkg=="__root__") continue;
fs::create_directories(fs::path(outDir)/pkg,ec);
// package overview
{ std::ostringstream po; renderPackage(po,ix,pkg);
std::ofstream pf((fs::path(outDir)/pkg/"_package.txt").string()); pf<<po.str(); }
auto& us=kv.second;
std::sort(us.begin(),us.end(),[](auto*a,auto*b){return a->name<b->name;});
for(auto* s:us){
++units;
UnitDoc u=parseUnit(*s,ix.root());
if(u.classes.empty()) continue;
std::ostringstream cp;
for(const auto& c:u.classes) renderClass(cp,u,c);
std::ofstream cf((fs::path(outDir)/pkg/(s->name+".txt")).string());
cf<<cp.str();
index<<pkg<<"\t"<<s->name<<"\n";
++pages;
}
}
std::cout<<"SleelaDoc corpus written to "<<outDir<<"\n"
<<" "<<byPkg.size()<<" package(s), "<<units<<" unit(s), "<<pages<<" class page(s), plus TOPICS.index\n";
return 0;
}
// ---- facade live OS search (deliverable #6) -------------------------------
// A facade-only package (e.g. psychiatry, politico) carries just an SLPackage
// marker under /lib; the real subject material lives elsewhere on disk (sibling
// top-level dirs, data, docs, scripts). `sleela docs --facade <topic>` searches
// the filesystem AT RUNTIME for files belonging to the topic and renders a
// facade report. The search is bounded by three user-overridable caps and
// always prints an honest, partial report naming whichever cap stopped it:
// --facade-max-mb N working-memory ceiling (default 6 MB)
// --facade-max-files N files examined ceiling (default 6000)
// --facade-max-seconds N wall-clock ceiling (default 360 = 6 min)
// --facade-root DIR where to search (default: the SLeeLa root; may
// be widened up to "/" at the user's choice)
struct FacadeCaps { size_t maxBytes=6*1024*1024; size_t maxFiles=6000; long maxSeconds=360; };
struct FacadeHit { std::string path; std::string kind; std::string peek; uintmax_t size=0; };
std::string classifyKind(const fs::path& p){
std::string e=lower(p.extension().string());
if(e==".sleela") return "source (.sleela)";
if(e==".md"||e==".txt"||e==".rst"||e==".adoc") return "document";
if(e==".c"||e==".h"||e==".cpp"||e==".hpp"||e==".cc"||e==".mm") return "native source";
if(e==".py"||e==".sh"||e==".ps1"||e==".bat") return "script";
if(e==".json"||e==".xml"||e==".csv"||e==".yaml"||e==".yml"||e==".sst"||e==".sheet") return "data";
if(e==".key"||e==".pem"||e==".bin") return "binary/key";
return "other";
}
bool looksText(const fs::path& p){
std::string e=lower(p.extension().string());
static const std::vector<std::string> bin={".key",".pem",".bin",".png",".jpg",".jpeg",".gif",".zip",".jar",".gz",".o",".a",".so",".class"};
for(const auto& b:bin) if(e==b) return false;
return true;
}
// First non-empty, non-trivial line of a text file, trimmed to 120 chars.
std::string firstLinePeek(const fs::path& p){
std::ifstream in(p); if(!in) return "";
std::string ln; int guard=0;
while(std::getline(in,ln) && guard++<40){
std::string s=trim(ln);
if(s.empty()) continue;
// skip pure comment/marker lines for a more useful peek
if(s.size()>120) s=s.substr(0,117)+"...";
return s;
}
return "";
}
// Should this directory be skipped during the walk?
bool skipDir(const std::string& name){
return name==".git" || name=="node_modules" || name=="build" ||
name==".cache" || name=="__pycache__" || name==".svn";
}
int renderFacade(std::ostream& o, const library::Index& ix, const std::string& topic,
const std::string& rootArg, const FacadeCaps& caps){
// Resolve the search root: explicit arg, else env, else the SLeeLa root
// (parent of /lib) so sibling top-level subject dirs are found by default.
std::string root=rootArg;
if(root.empty()) if(const char* e=std::getenv("SLEELA_FACADE_PATH"); e&&*e) root=e;
if(root.empty()){ fs::path lib(ix.root()); root=(lib.has_parent_path()?lib.parent_path():lib).generic_string(); }
fs::path rootP(root);
std::error_code ec;
if(!fs::is_directory(rootP,ec)){ o<<"sleela docs --facade: search root is not a directory: "<<root<<"\n"; return 1; }
std::string tL=lower(topic);
rule(o);
o<<" facade "<<topic<<" (live OS search)\n";
rule(o);
o<<"\nsearch root : "<<fs::weakly_canonical(rootP,ec).generic_string();
if(ec){ ec.clear(); o<<root; }
o<<"\ncaps : "<<(caps.maxBytes/(1024*1024))<<" MB working memory, "
<<caps.maxFiles<<" files, "<<caps.maxSeconds<<" s wall-clock\n\n";
std::vector<FacadeHit> hits;
size_t filesSeen=0, bytesHeld=0, dirsSeen=0;
auto t0=std::chrono::steady_clock::now();
const char* stopReason=nullptr;
bool topicDirMatch=false;
auto elapsedS=[&]{ return (long)std::chrono::duration_cast<std::chrono::seconds>(std::chrono::steady_clock::now()-t0).count(); };
// PHASE 1 -- locate directories named <topic> (case-insensitive) anywhere
// under the root. A facade topic's real material lives in a directory of
// that name; finding those first lets the file caps apply to the RELEVANT
// subtree(s) rather than being spent walking unrelated trees. The dir scan
// is itself bounded by the file/time caps (counting directories visited).
std::vector<fs::path> topicDirs;
// If the root directory itself is named the topic, it is a match -- a user
// who points --facade-root straight at the topic dir expects its contents.
{
fs::path canon=fs::weakly_canonical(rootP,ec); if(ec){ ec.clear(); canon=rootP; }
if(lower(canon.filename().string())==tL) topicDirs.push_back(rootP);
}
{
fs::recursive_directory_iterator dit(rootP, fs::directory_options::skip_permission_denied, ec), dend;
if(ec){ o<<"(cannot read search root: "<<ec.message()<<")\n"; return 1; }
for(; dit!=dend; dit.increment(ec)){
if(ec){ ec.clear(); continue; }
if(elapsedS()>=caps.maxSeconds){ stopReason="time"; break; }
std::error_code dec; if(!dit->is_directory(dec)){ dec.clear(); continue; }
const fs::path& d=dit->path();
if(skipDir(d.filename().string())){ dit.disable_recursion_pending(); continue; }
if(++dirsSeen>=caps.maxFiles){ stopReason="files"; break; } // reuse the files cap for the dir scan
if(lower(d.filename().string())==tL) topicDirs.push_back(d);
}
}
// PHASE 2 -- within each matched topic directory, collect its FOLDERS and
// its regular files (recursively), honoring the three caps. The folders are
// the shape of the subject; the files follow as a matter of natural motion.
// Every directory and file under a topic-named directory belongs to the
// topic. The matched topic directories themselves are folders of record.
std::vector<FacadeHit> folders;
auto addFolder=[&](const fs::path& d){
FacadeHit f; f.path=d.generic_string(); f.kind="folder"; f.size=0;
size_t cost=f.path.size()+64; if(bytesHeld+cost>caps.maxBytes){ stopReason="memory"; return false; }
bytesHeld+=cost; folders.push_back(std::move(f)); return true;
};
if(!stopReason)
for(const auto& base:topicDirs){
topicDirMatch=true;
if(!addFolder(base)) break; // the topic folder itself
fs::recursive_directory_iterator it(base, fs::directory_options::skip_permission_denied, ec), end;
if(ec){ ec.clear(); continue; }
for(; it!=end; it.increment(ec)){
if(ec){ ec.clear(); continue; }
if(elapsedS()>=caps.maxSeconds){ stopReason="time"; break; }
std::error_code fec;
if(it->is_directory(fec)){
if(skipDir(it->path().filename().string())){ it.disable_recursion_pending(); continue; }
if(++dirsSeen>=caps.maxFiles){ stopReason="files"; break; }
if(!addFolder(it->path())){ break; } // folders shown implicitly
continue;
}
if(fec){ fec.clear(); continue; }
if(!it->is_regular_file(fec)){ fec.clear(); continue; }
if(++filesSeen>=caps.maxFiles){ stopReason="files"; break; }
const fs::path& p=it->path();
FacadeHit h; h.path=p.generic_string(); h.kind=classifyKind(p);
h.size=fs::file_size(p,fec); if(fec){ fec.clear(); h.size=0; }
if(looksText(p)) h.peek=firstLinePeek(p);
size_t cost=h.path.size()+h.peek.size()+64;
if(bytesHeld+cost>caps.maxBytes){ stopReason="memory"; break; }
bytesHeld+=cost; hits.push_back(std::move(h));
}
if(stopReason) break;
}
// Group by kind for a legible report.
std::sort(hits.begin(),hits.end(),[](const FacadeHit&a,const FacadeHit&b){
if(a.kind!=b.kind) return a.kind<b.kind; return a.path<b.path; });
std::sort(folders.begin(),folders.end(),[](const FacadeHit&a,const FacadeHit&b){return a.path<b.path;});
if(hits.empty() && folders.empty()){
o<<"No folders or files found for topic '"<<topic<<"' under the search root.\n";
if(!topicDirMatch) o<<" (no path component named '"<<topic<<"' was seen; try --facade-root <dir> to widen)\n";
} else {
// Folders first -- the shape of the subject, shown implicitly.
if(!folders.empty()){
o<<folders.size()<<" folder(s) of '"<<topic<<"':\n\n[folder]\n";
for(const auto& f:folders) o<<" "<<f.path<<"/\n";
o<<"\n";
}
o<<hits.size()<<" file(s) belonging to '"<<topic<<"' (the files follow as natural motion):\n";
std::string lastKind;
for(const auto& h:hits){
if(h.kind!=lastKind){ o<<"\n["<<h.kind<<"]\n"; lastKind=h.kind; }
o<<" "<<h.path<<" ("<<h.size<<" bytes)\n";
if(!h.peek.empty()) o<<" "<<h.peek<<"\n";
}
// For any .sleela sources found, render their full class pages too.
bool anySrc=false;
for(const auto& h:hits) if(h.kind=="source (.sleela)"){ anySrc=true; break; }
if(anySrc){
o<<"\n"<<std::string(74,'-')<<"\nRENDERED SOURCE PAGES\n"<<std::string(74,'-')<<"\n";
for(const auto& h:hits){
if(h.kind!="source (.sleela)") continue;
library::Symbol sym{topic, fs::path(h.path).stem().string(), h.path};
UnitDoc u=parseUnit(sym, ix.root());
u.path=h.path; // show the real discovered path
for(const auto& c:u.classes) renderClass(o,u,c);
}
}
}
long elapsed=elapsedS();
o<<"\n"<<std::string(74,'=')<<"\n";
o<<"scanned "<<dirsSeen<<" dir(s), collected "<<filesSeen<<" file(s) in "<<elapsed<<" s; held ~"<<(bytesHeld/1024)<<" KB.\n";
if(stopReason) o<<"NOTE: stopped early -- "<<stopReason<<" cap reached ("
<<(std::string(stopReason)=="memory"? std::to_string(caps.maxBytes/(1024*1024))+" MB"
: std::string(stopReason)=="files"? std::to_string(caps.maxFiles)+" files"
: std::to_string(caps.maxSeconds)+" s")
<<"). Raise it with --facade-max-"<<(std::string(stopReason)=="memory"?"mb":stopReason==std::string("files")?"files":"seconds")<<" N, or narrow --facade-root.\n";
else o<<"complete (no cap reached).\n";
return 0;
}
} // namespace
int docsCmd(int argc, char** argv){
// Collect the topic words that follow the "docs" command token. The driver
// may or may not have resliced argv (it only does so when global options
// preceded the command), so locate "docs" and take everything after it.
std::vector<std::string> words;
int docsAt=-1;
for(int i=0;i<argc;++i) if(std::string(argv[i])=="docs"){ docsAt=i; break; }
int firstWord=(docsAt>=0)?docsAt+1:1;
for(int i=firstWord;i<argc;++i) words.push_back(argv[i]);
library::Index ix = library::Index::discover();
if(ix.empty()){
std::cerr<<"sleela docs: could not locate the /lib source tree.\n"
" Set SLEELA_LIB or run from the SLeeLa checkout.\n";
return 1;
}
std::ostream& o=std::cout;
// Facade live OS search: `sleela docs --facade <topic> [--facade-root DIR]
// [--facade-max-mb N] [--facade-max-files N] [--facade-max-seconds N]`.
// Also auto-offered when a plain topic resolves to a facade-only package.
{
bool facade=false; std::string facadeRoot; FacadeCaps caps; std::string facadeTopic;
std::vector<std::string> rest;
for(size_t i=0;i<words.size();++i){
const std::string& w=words[i];
auto next=[&](const char* flag)->std::string{ if(i+1<words.size()){ return words[++i]; } std::cerr<<"sleela docs: "<<flag<<" needs a value\n"; return ""; };
if(w=="--facade"||w=="-f") facade=true;
else if(w=="--facade-root") facadeRoot=next("--facade-root");
else if(w.rfind("--facade-root=",0)==0) facadeRoot=w.substr(14);
else if(w=="--facade-max-mb"){ std::string v=next("--facade-max-mb"); if(!v.empty()) caps.maxBytes=(size_t)std::strtoull(v.c_str(),nullptr,10)*1024*1024; }
else if(w=="--facade-max-files"){ std::string v=next("--facade-max-files"); if(!v.empty()) caps.maxFiles=(size_t)std::strtoull(v.c_str(),nullptr,10); }
else if(w=="--facade-max-seconds"){ std::string v=next("--facade-max-seconds"); if(!v.empty()) caps.maxSeconds=std::strtol(v.c_str(),nullptr,10); }
else rest.push_back(w);
}
if(facade){
if(rest.empty()){ std::cerr<<"sleela docs --facade: name a topic, e.g. 'sleela docs --facade psychiatry'\n"; return 2; }
return renderFacade(o,ix,rest.back(),facadeRoot,caps);
}
}
// Corpus generation: `sleela docs --generate [dir]`.
if(!words.empty() && (words[0]=="--generate"||words[0]=="-g")){
std::string dir = (words.size()>=2)? words[1] : corpusDir(ix);
return generateCorpus(ix,dir);
}
// Prefer a pre-generated corpus unless the caller forces live parsing with
// `--live`. When forced, drop the flag and continue.
bool forceLive=false;
if(!words.empty() && words[0]=="--live"){ forceLive=true; words.erase(words.begin()); }
std::string cdir=corpusDir(ix);
bool haveCorpus = !forceLive && fs::is_directory(cdir);
if(words.empty()){ listAll(o,ix); return 0; }
// Two-word form: <package> <Class>
if(words.size()>=2){
const std::string& pkg=words[0]; const std::string& cls=words[1];
for(const auto& s:ix.symbols()) if(lower(s.package)==lower(pkg) && lower(s.name)==lower(cls)){
if(haveCorpus && serveCached(o,cdir,s.package,s.name)) return 0;
UnitDoc u=parseUnit(s,ix.root());
if(u.classes.empty()){ o<<"(unit '"<<s.name<<"' declares no class)\n"; return 0; }
for(const auto& c:u.classes) renderClass(o,u,c);
return 0;
}
// fall through to single-topic resolution on the second word
}
const std::string topic=words.size()>=2?words[1]:words[0];
std::string tL=lower(topic);
// 1) exact package?
if(ix.hasPackage(topic) || [&]{ for(const auto& s:ix.symbols()) if(lower(s.package)==tL) return true; return false; }()){
std::string pkg; for(const auto& s:ix.symbols()) if(lower(s.package)==tL){ pkg=s.package; break; }
if(pkg.empty()) pkg=topic;
renderPackage(o,ix,pkg);
return 0;
}
// 2) exact class (case-insensitive)? Collect EVERY match so a name shared
// across packages disambiguates rather than silently picking one. Prefer
// units that actually declare a class, and rank SL* standard-library
// units ahead of the large java compat mirror.
std::vector<library::Symbol> exact;
std::string slForm = "sl"+tL; // standard-library classes are SL-prefixed
for(const auto& s:ix.symbols()){ std::string nL=lower(s.name); if(nL==tL || nL==slForm) exact.push_back(s); }
if(!exact.empty()){
auto rank=[](const library::Symbol& s){
int r=0;
if(s.package=="java") r+=100; // compat mirror: deprioritise
if(s.path.find("early_access")!=std::string::npos) r+=50;
if(s.name.rfind("SL",0)==0) r-=10; // SL* standard library: prefer
return r;
};
std::sort(exact.begin(),exact.end(),[&](const library::Symbol&a,const library::Symbol&b){return rank(a)<rank(b);});
// Keep only matches that declare a class; if none do, fall back to all.
std::vector<std::pair<library::Symbol,UnitDoc>> good;
for(const auto& s:exact){ UnitDoc u=parseUnit(s,ix.root()); if(!u.classes.empty()) good.push_back({s,u}); }
if(good.empty()){ o<<"(no class declaration found for '"<<topic<<"')\n\n"; suggestNear(o,ix,topic); return 0; }
if(good.size()>1){
o<<"'"<<topic<<"' names "<<good.size()<<" units across packages. Pick one:\n\n";
for(const auto& g:good) o<<" sleela docs "<<g.first.package<<" "<<g.first.name<<"\n";
o<<"\nShowing the best standard-library match ("<<good.front().first.package<<"):\n\n";
}
const auto& g=good.front();
if(haveCorpus && serveCached(o,cdir,g.first.package,g.first.name)) return 0;
for(const auto& c:g.second.classes) renderClass(o,g.second,c);
return 0;
}
// 3) near results
suggestNear(o,ix,topic);
return 0;
}
} // namespace sleela