@mcoda/core 0.1.33 → 0.1.35

package/dist/services/planning/SdsCoverageModel.d.ts

@@ -0,0 +1,27 @@
+export interface SdsCoverageSignalSet {
+    rawSectionHeadings: string[];
+    rawFolderEntries: string[];
+    sectionHeadings: string[];
+    folderEntries: string[];
+    skippedHeadingSignals: number;
+    skippedFolderSignals: number;
+}
+export interface SdsCoverageSummary {
+    coverageRatio: number;
+    totalSignals: number;
+    missingSectionHeadings: string[];
+    missingFolderEntries: string[];
+}
+export declare const normalizeCoverageText: (value: string) => string;
+export declare const normalizeCoverageAnchor: (kind: "section" | "folder", value: string) => string;
+export declare const collectSdsCoverageSignalsFromDocs: (docs: Array<{
+    content?: string | null;
+}>, options: {
+    headingLimit: number;
+    folderLimit: number;
+}) => SdsCoverageSignalSet;
+export declare const evaluateSdsCoverage: (corpus: string, signals: {
+    sectionHeadings: string[];
+    folderEntries: string[];
+}, existingAnchors?: Set<string>) => SdsCoverageSummary;
+//# sourceMappingURL=SdsCoverageModel.d.ts.map

package/dist/services/planning/SdsCoverageModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SdsCoverageModel.d.ts","sourceRoot":"","sources":["../../../src/services/planning/SdsCoverageModel.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,oBAAoB;IACnC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,eAAO,MAAM,qBAAqB,GAAI,OAAO,MAAM,KAAG,MAM3C,CAAC;AAEZ,eAAO,MAAM,uBAAuB,GAAI,MAAM,SAAS,GAAG,QAAQ,EAAE,OAAO,MAAM,KAAG,MACb,CAAC;AA6ExE,eAAO,MAAM,iCAAiC,GAC5C,MAAM,KAAK,CAAC;IAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,EACxC,SAAS;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,KACrD,oBAmBF,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,MAAM,EACd,SAAS;IAAE,eAAe,EAAE,MAAM,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,EAC/D,kBAAiB,GAAG,CAAC,MAAM,CAAa,KACvC,kBAoBF,CAAC"}

package/dist/services/planning/SdsCoverageModel.js

@@ -0,0 +1,138 @@
+import { collectSdsImplementationSignals, normalizeFolderEntry, normalizeHeadingCandidate, } from "./SdsStructureSignals.js";
+const coverageStopTokens = new Set([
+    "about",
+    "across",
+    "after",
+    "before",
+    "between",
+    "from",
+    "into",
+    "over",
+    "under",
+    "using",
+    "with",
+    "without",
+    "onto",
+    "the",
+    "and",
+    "for",
+    "of",
+    "to",
+]);
+const unique = (items) => Array.from(new Set(items.filter(Boolean)));
+export const normalizeCoverageText = (value) => value
+    .toLowerCase()
+    .replace(/[`*_]/g, " ")
+    .replace(/[^a-z0-9/\s.-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+export const normalizeCoverageAnchor = (kind, value) => `${kind}:${normalizeCoverageText(value).replace(/\s+/g, " ").trim()}`;
+const tokenizeCoverageSignal = (value) => unique(value
+    .split(/\s+/)
+    .map((token) => token.replace(/[^a-z0-9._-]+/g, ""))
+    .filter((token) => token.length >= 3 && !coverageStopTokens.has(token)));
+const buildBigrams = (tokens) => {
+    const bigrams = [];
+    for (let index = 0; index < tokens.length - 1; index += 1) {
+        const left = tokens[index];
+        const right = tokens[index + 1];
+        if (!left || !right)
+            continue;
+        bigrams.push(`${left} ${right}`);
+    }
+    return unique(bigrams);
+};
+const headingCovered = (corpus, heading) => {
+    const normalized = normalizeCoverageText(normalizeHeadingCandidate(heading));
+    if (!normalized)
+        return true;
+    if (corpus.includes(normalized))
+        return true;
+    const tokens = tokenizeCoverageSignal(normalized).slice(0, 10);
+    if (tokens.length === 0)
+        return true;
+    const hitCount = tokens.filter((token) => corpus.includes(token)).length;
+    const requiredHits = tokens.length <= 2
+        ? tokens.length
+        : tokens.length <= 4
+            ? 2
+            : Math.min(4, Math.ceil(tokens.length * 0.6));
+    if (hitCount < requiredHits)
+        return false;
+    if (tokens.length >= 3) {
+        const longestToken = tokens.reduce((longest, token) => (token.length > longest.length ? token : longest), "");
+        if (longestToken.length >= 6 && !corpus.includes(longestToken))
+            return false;
+    }
+    const bigrams = buildBigrams(tokens);
+    if (tokens.length >= 3 && bigrams.length > 0 && !bigrams.some((bigram) => corpus.includes(bigram))) {
+        return false;
+    }
+    return true;
+};
+const folderEntryCovered = (corpus, entry) => {
+    const normalizedEntry = normalizeFolderEntry(entry)?.toLowerCase().replace(/\/+/g, "/");
+    if (!normalizedEntry)
+        return true;
+    const corpusTight = corpus.replace(/\s+/g, "");
+    if (corpusTight.includes(normalizedEntry.replace(/\s+/g, "")))
+        return true;
+    const segments = normalizedEntry
+        .split("/")
+        .map((segment) => segment.trim().replace(/[^a-z0-9._-]+/g, ""))
+        .filter(Boolean);
+    if (segments.length === 0)
+        return true;
+    const tailSegments = unique(segments.slice(Math.max(0, segments.length - 3)));
+    const hitCount = tailSegments.filter((segment) => corpus.includes(segment)).length;
+    const requiredHits = tailSegments.length <= 1 ? 1 : Math.min(2, tailSegments.length);
+    if (hitCount < requiredHits)
+        return false;
+    if (tailSegments.length >= 2) {
+        const hasStrongTokenMatch = tailSegments.some((segment) => segment.length >= 5 && corpus.includes(segment));
+        if (!hasStrongTokenMatch)
+            return false;
+    }
+    return true;
+};
+export const collectSdsCoverageSignalsFromDocs = (docs, options) => {
+    const docSignals = docs.map((doc) => collectSdsImplementationSignals(doc.content ?? "", {
+        headingLimit: options.headingLimit,
+        folderLimit: options.folderLimit,
+    }));
+    const rawSectionHeadings = unique(docSignals.flatMap((signals) => signals.rawSectionHeadings));
+    const rawFolderEntries = unique(docSignals.flatMap((signals) => signals.rawFolderEntries));
+    const sectionHeadings = unique(docSignals.flatMap((signals) => signals.sectionHeadings)).slice(0, options.headingLimit);
+    const folderEntries = unique(docSignals.flatMap((signals) => signals.folderEntries)).slice(0, options.folderLimit);
+    return {
+        rawSectionHeadings,
+        rawFolderEntries,
+        sectionHeadings,
+        folderEntries,
+        skippedHeadingSignals: Math.max(0, rawSectionHeadings.length - sectionHeadings.length),
+        skippedFolderSignals: Math.max(0, rawFolderEntries.length - folderEntries.length),
+    };
+};
+export const evaluateSdsCoverage = (corpus, signals, existingAnchors = new Set()) => {
+    const missingSectionHeadings = signals.sectionHeadings.filter((heading) => {
+        const anchor = normalizeCoverageAnchor("section", heading);
+        if (existingAnchors.has(anchor))
+            return false;
+        return !headingCovered(corpus, heading);
+    });
+    const missingFolderEntries = signals.folderEntries.filter((entry) => {
+        const anchor = normalizeCoverageAnchor("folder", entry);
+        if (existingAnchors.has(anchor))
+            return false;
+        return !folderEntryCovered(corpus, entry);
+    });
+    const totalSignals = signals.sectionHeadings.length + signals.folderEntries.length;
+    const coveredSignals = totalSignals - missingSectionHeadings.length - missingFolderEntries.length;
+    const coverageRatio = totalSignals === 0 ? 1 : coveredSignals / totalSignals;
+    return {
+        coverageRatio: Number(coverageRatio.toFixed(4)),
+        totalSignals,
+        missingSectionHeadings,
+        missingFolderEntries,
+    };
+};

package/dist/services/planning/SdsPreflightService.d.ts

@@ -59,7 +59,9 @@ export declare class SdsPreflightService {
     private walkCandidates;
     private collectPathCandidates;
     private discoverSdsPaths;
+    private countSdsSectionSignals;
     private isLikelySdsPath;
+    private selectLikelySdsPaths;
     private resolveSdsPaths;
     private buildArtifacts;
     private getGateRunners;

package/dist/services/planning/SdsPreflightService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SdsPreflightService.d.ts","sourceRoot":"","sources":["../../../src/services/planning/SdsPreflightService.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SdsPreflightService.d.ts","sourceRoot":"","sources":["../../../src/services/planning/SdsPreflightService.ts"],"names":[],"mappings":"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"}

package/dist/services/planning/SdsPreflightService.js

@@ -32,8 +32,24 @@ const ignoredDirs = new Set([
     "tmp",
     "temp",
 ]);
-const sdsFilenamePattern = /(sds|software[-_ ]design|system[-_ ]design|design[-_ ]spec|architecture)/i;
-const sdsContentPattern = /(software design specification|system design specification|^#\s*sds\b)/im;
+const strongSdsFilenamePattern = /(sds|software[-_ ]design|system[-_ ]design|design[-_ ]spec)/i;
+const strongSdsDirectoryPattern = /(?:^|[/\\])sds(?:[/\\]|$)/i;
+const weakSdsFilenamePattern = /architecture/i;
+const sdsTitlePattern = /^#\s*(?:software design specification|system design specification|sds)\b/im;
+const nonSdsTitlePattern = /^#\s*(?:product design review|pdr|request for proposal|rfp)\b/im;
+const sdsSectionPatterns = [
+    /^#{1,6}\s+open questions\b/im,
+    /^#{1,6}\s+folder tree\b/im,
+    /^#{1,6}\s+technology stack\b/im,
+    /^#{1,6}\s+policy(?: and cache consent)?\b/im,
+    /^#{1,6}\s+telemetry\b/im,
+    /^#{1,6}\s+(?:metering and usage|metering|usage)\b/im,
+    /^#{1,6}\s+(?:operations and deployment|operations|deployment)\b/im,
+    /^#{1,6}\s+observability\b/im,
+    /^#{1,6}\s+testing gates\b/im,
+    /^#{1,6}\s+(?:failure recovery and rollback|failure modes(?:, recovery, and rollback)?)\b/im,
+    /^#{1,6}\s+external integrations and adapter contracts\b/im,
+];
 const markdownPattern = /\.(md|markdown|txt|rst)$/i;
 const unresolvedTokenPattern = /\b(TBD|TBC|TODO|FIXME|to be determined|to be decided|unknown|unresolved)\b/gi;
 const sdsHeadingLinePattern = /^#{1,6}\s+(.+)$/;
@@ -78,6 +94,14 @@ const environmentMatchers = [
     { label: "staging", pattern: /\bstaging\b|\bpre-?prod\b/i },
     { label: "production", pattern: /\bprod(uction)?\b/i },
 ];
+const documentationSegmentPattern = /^(docs?|design|specs?|runbooks?|adr|architecture)$/i;
+const implementationSegmentPattern = /^(src|app|apps|service|services|worker|workers|module|modules|package|packages|lib|libs|engine|engines|console|consoles|runtime|runtimes)$/i;
+const interfaceSegmentPattern = /^(api|apis|openapi|swagger|graphql|proto|schema|schemas|contract|contracts|interface|interfaces)$/i;
+const storageSegmentPattern = /^(db|data|storage|schema|schemas|migration|migrations|sql|seed|seeds)$/i;
+const automationSegmentPattern = /^(script|scripts|tool|tools|bin|cmd|cli|automation)$/i;
+const operationsSegmentPattern = /^(ops|deploy|deployment|deployments|infra|infrastructure|terraform|helm|k8s|kubernetes|systemd)$/i;
+const validationSegmentPattern = /^(test|tests|testing|spec|specs|e2e|qa|fixtures)$/i;
+const staticAssetSegmentPattern = /^(public|static|assets)$/i;
 const moduleNoiseTokens = new Set([
     "and",
     "for",
@@ -101,6 +125,47 @@ const moduleNoiseTokens = new Set([
 ]);
 const execFileAsync = promisify(execFile);
 const uniqueStrings = (values) => Array.from(new Set(values.filter(Boolean)));
+const stripManagedPreflightBlocks = (content) => {
+    let updated = content;
+    while (true) {
+        const startIndex = updated.indexOf(MANAGED_SDS_BLOCK_START);
+        if (startIndex < 0)
+            break;
+        const endIndex = updated.indexOf(MANAGED_SDS_BLOCK_END, startIndex);
+        if (endIndex < 0)
+            break;
+        updated = `${updated.slice(0, startIndex)}\n${updated.slice(endIndex + MANAGED_SDS_BLOCK_END.length)}`;
+    }
+    return updated;
+};
+const describeFolderEntry = (entry) => {
+    if (/\s+#/.test(entry))
+        return "";
+    const segments = entry
+        .replace(/^\.?\//, "")
+        .split("/")
+        .map((segment) => segment.trim().toLowerCase())
+        .filter(Boolean);
+    if (segments.length === 0)
+        return "implementation surface";
+    if (segments.some((segment) => documentationSegmentPattern.test(segment)))
+        return "documentation and planning inputs";
+    if (segments.some((segment) => validationSegmentPattern.test(segment)))
+        return "automated validation surfaces";
+    if (segments.some((segment) => automationSegmentPattern.test(segment)))
+        return "automation and command entrypoints";
+    if (segments.some((segment) => operationsSegmentPattern.test(segment)))
+        return "deployment and operations assets";
+    if (segments.some((segment) => storageSegmentPattern.test(segment)))
+        return "storage and schema assets";
+    if (segments.some((segment) => interfaceSegmentPattern.test(segment)))
+        return "interface definitions and compatibility surfaces";
+    if (segments.some((segment) => staticAssetSegmentPattern.test(segment)))
+        return "runtime assets";
+    if (segments.some((segment) => implementationSegmentPattern.test(segment)))
+        return "implementation surfaces";
+    return segments.length >= 2 ? "implementation surface" : "top-level workspace surface";
+};
 const normalizeQuestion = (value) => value
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, " ")
@@ -213,25 +278,34 @@ export class SdsPreflightService {
         });
         return uniqueStrings(discovered).slice(0, SDS_SCAN_MAX_FILES);
     }
+    countSdsSectionSignals(sample) {
+        const effectiveSample = stripManagedPreflightBlocks(sample);
+        return sdsSectionPatterns.reduce((count, pattern) => count + (pattern.test(effectiveSample) ? 1 : 0), 0);
+    }
     async isLikelySdsPath(filePath) {
         const baseName = path.basename(filePath);
-        if (sdsFilenamePattern.test(baseName))
-            return true;
+        const normalizedPath = filePath.replace(/\\/g, "/");
         try {
-            const sample = (await fs.readFile(filePath, "utf8")).slice(0, 35000);
-            return sdsContentPattern.test(sample);
+            const rawSample = (await fs.readFile(filePath, "utf8")).slice(0, 35000);
+            const sample = stripManagedPreflightBlocks(rawSample);
+            if (nonSdsTitlePattern.test(sample))
+                return false;
+            if (sdsTitlePattern.test(sample))
+                return true;
+            if (strongSdsFilenamePattern.test(baseName) || strongSdsDirectoryPattern.test(normalizedPath)) {
+                return true;
+            }
+            if (!weakSdsFilenamePattern.test(baseName))
+                return false;
+            return this.countSdsSectionSignals(sample) >= 3;
         }
         catch {
             return false;
         }
     }
-    async resolveSdsPaths(options) {
-        const explicit = await this.collectPathCandidates(options.sdsPaths);
-        const fromInputs = await this.collectPathCandidates(options.inputPaths);
-        const discovered = await this.discoverSdsPaths();
-        const candidatePaths = uniqueStrings([...explicit, ...fromInputs, ...discovered]).slice(0, SDS_SCAN_MAX_FILES);
+    async selectLikelySdsPaths(candidatePaths) {
         const selected = [];
-        for (const candidate of candidatePaths) {
+        for (const candidate of uniqueStrings(candidatePaths).slice(0, SDS_SCAN_MAX_FILES)) {
             if (await this.isLikelySdsPath(candidate)) {
                 selected.push(path.resolve(candidate));
             }
@@ -240,6 +314,19 @@ export class SdsPreflightService {
         }
         return uniqueStrings(selected);
     }
+    async resolveSdsPaths(options) {
+        const explicit = await this.collectPathCandidates(options.sdsPaths);
+        if (explicit.length > 0) {
+            return this.selectLikelySdsPaths(explicit);
+        }
+        const fromInputs = await this.collectPathCandidates(options.inputPaths);
+        const selectedFromInputs = await this.selectLikelySdsPaths(fromInputs);
+        if (selectedFromInputs.length > 0) {
+            return selectedFromInputs;
+        }
+        const discovered = await this.discoverSdsPaths();
+        return this.selectLikelySdsPaths(discovered);
+    }
     buildArtifacts(sdsPath) {
         const artifacts = createEmptyArtifacts();
         artifacts.sds = {
@@ -286,7 +373,7 @@ export class SdsPreflightService {
         return path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(this.workspace.workspaceRoot, filePath);
     }
     collectSignalsFromContent(content) {
-        const lines = content.split(/\r?\n/);
+        const lines = stripManagedPreflightBlocks(content).split(/\r?\n/);
         const headings = [];
         const folderEntries = [];
         for (const line of lines) {
@@ -445,12 +532,17 @@ export class SdsPreflightService {
     }
     managedFolderTreeSection(signals) {
         const entries = signals?.folderEntries?.slice(0, 10) ?? [];
+        const annotateEntry = (entry, isLast) => {
+            const hint = describeFolderEntry(entry);
+            const prefix = isLast ? "└──" : "├──";
+            return hint ? `${prefix} ${entry}  # ${hint}` : `${prefix} ${entry}`;
+        };
         if (entries.length > 0) {
             return [
                 "## Folder Tree",
                 "```text",
                 ".",
-                ...entries.map((entry, index) => `${index === entries.length - 1 ? "└──" : "├──"} ${entry}`),
+                ...entries.map((entry, index) => annotateEntry(entry, index === entries.length - 1)),
                 "```",
                 "",
             ];
@@ -459,14 +551,12 @@ export class SdsPreflightService {
             "## Folder Tree",
             "```text",
             ".",
-            "├── docs/",
-            "├── apps/web/",
-            "├── services/api/",
-            "├── services/worker/",
-            "├── packages/shared/",
-            "├── db/migrations/",
-            "├── tests/",
-            "└── scripts/",
+            "├── docs/architecture/  # documentation and planning inputs",
+            "├── modules/core/  # implementation surfaces",
+            "├── interfaces/public/  # interface definitions and compatibility surfaces",
+            "├── data/migrations/  # storage and schema assets",
+            "├── tests/integration/  # automated validation surfaces",
+            "└── tools/release/  # automation and command entrypoints",
             "```",
             "",
         ];
@@ -878,24 +968,24 @@ export class SdsPreflightService {
         const scopedIssues = issues.filter((issue) => this.issueMatchesPath(issue, sdsPath));
         const lines = [
             MANAGED_SDS_BLOCK_START,
-            "## Open Questions (Resolved)",
+            "## Planning Decisions (mcoda preflight)",
             "",
         ];
         if (scopedQuestions.length === 0) {
-            lines.push("- Resolved: No unresolved questions remain for this SDS file in this preflight run.");
+            lines.push("- Decision coverage baseline recorded for this SDS file in this preflight run.");
             lines.push("");
         }
         else {
             scopedQuestions.forEach((question, index) => {
                 const summary = this.normalizeResolvedText(question.answer);
-                const prefix = summary || "Explicit decision recorded in managed preflight output.";
-                lines.push(`- Resolved: Decision ${index + 1} for "${question.question}" => ${prefix}`);
+                const prefix = summary || "Explicit implementation decision recorded in managed preflight output.";
+                lines.push(`- Decision ${index + 1}: ${prefix}`);
             });
             lines.push("");
         }
-        lines.push("## Resolved Decisions (mcoda preflight)");
-        lines.push("- Decision baseline: unresolved items are converted into explicit implementation decisions.");
-        lines.push("- Planning rule: each resolved decision must map to implementation and QA verification work.");
+        lines.push("## Decision Summary (mcoda preflight)");
+        lines.push("- Decision baseline: preflight converts planning ambiguities into explicit implementation guidance.");
+        lines.push("- Planning rule: each captured decision maps to implementation and QA verification work.");
         if (signals?.moduleDomains && signals.moduleDomains.length > 0) {
             lines.push(`- Module scope detected for this SDS file: ${signals.moduleDomains.slice(0, 6).join(", ")}.`);
         }
@@ -908,12 +998,13 @@ export class SdsPreflightService {
         lines.push("## Gap Remediation Summary (mcoda preflight)");
         lines.push("");
         if (scopedIssues.length === 0) {
-            lines.push("- No unresolved SDS quality gaps remained for this SDS file in this preflight run.");
+            lines.push("- No remaining SDS quality gaps were detected for this SDS file in this preflight run.");
             lines.push("");
         }
         else {
             scopedIssues.forEach((issue, index) => {
-                lines.push(`### Gap ${index + 1}: ${issue.message}`);
+                const gapSummary = this.normalizeResolvedText(issue.message) || issue.message;
+                lines.push(`### Gap ${index + 1}: ${gapSummary}`);
                 lines.push(`- Gate: ${issue.gateId}`);
                 lines.push(`- Source: ${formatIssueLocation(issue)}`);
                 lines.push("- Remediation:");
@@ -1022,6 +1113,9 @@ export class SdsPreflightService {
         let issues = this.dedupeIssues(outcome.issues);
         let questions = this.extractQuestionAnswers(issues, signalsByPath);
         const applyToSds = options.applyToSds === true;
+        if (options.commitAppliedChanges && !applyToSds) {
+            warnings.push("SDS preflight commit was requested without applyToSds; skipping commit because source SDS writeback is disabled.");
+        }
         let appliedSdsPaths = [];
         if (applyToSds) {
             const applyResult = await this.applyPreflightRemediationsToSds({

package/dist/services/planning/SdsStructureSignals.d.ts

@@ -0,0 +1,24 @@
+export declare const isStructuredFilePath: (value: string) => boolean;
+export declare const stripManagedSdsPreflightBlock: (value: string | undefined) => string | undefined;
+export declare const normalizeHeadingCandidate: (value: string) => string;
+export declare const headingLooksImplementationRelevant: (heading: string) => boolean;
+export declare const pruneParentImplementationHeadings: (headings: string[]) => string[];
+export declare const normalizeStructuredPathToken: (value: string) => string | undefined;
+export declare const normalizeFolderEntry: (entry: string) => string | undefined;
+export declare const extractStructuredPaths: (content: string, limit: number) => string[];
+export declare const extractMarkdownHeadings: (content: string, limit: number) => string[];
+export declare const folderEntryLooksRepoRelevant: (entry: string) => boolean;
+export declare const filterImplementationStructuredPaths: (paths: string[]) => string[];
+export interface SdsImplementationSignals {
+    rawSectionHeadings: string[];
+    rawFolderEntries: string[];
+    sectionHeadings: string[];
+    folderEntries: string[];
+    skippedHeadingSignals: number;
+    skippedFolderSignals: number;
+}
+export declare const collectSdsImplementationSignals: (content: string, options: {
+    headingLimit: number;
+    folderLimit: number;
+}) => SdsImplementationSignals;
+//# sourceMappingURL=SdsStructureSignals.d.ts.map

package/dist/services/planning/SdsStructureSignals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SdsStructureSignals.d.ts","sourceRoot":"","sources":["../../../src/services/planning/SdsStructureSignals.ts"],"names":[],"mappings":"AA4GA,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,OAA6C,CAAC;AAEnG,eAAO,MAAM,6BAA6B,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,SAIlF,CAAC;AAEF,eAAO,MAAM,yBAAyB,GAAI,OAAO,MAAM,KAAG,MAGzD,CAAC;AAEF,eAAO,MAAM,kCAAkC,GAAI,SAAS,MAAM,KAAG,OAgBpE,CAAC;AAEF,eAAO,MAAM,iCAAiC,GAAI,UAAU,MAAM,EAAE,KAAG,MAAM,EAc5E,CAAC;AAEF,eAAO,MAAM,4BAA4B,GAAI,OAAO,MAAM,KAAG,MAAM,GAAG,SA4BrE,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,MAAM,GAAG,SACiC,CAAC;AA8DhG,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,EAAE,OAAO,MAAM,KAAG,MAAM,EA0B7E,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,SAAS,MAAM,EAAE,OAAO,MAAM,KAAG,MAAM,EAsC9E,CAAC;AAaF,eAAO,MAAM,4BAA4B,GAAI,OAAO,MAAM,KAAG,OAiB5D,CAAC;AAEF,eAAO,MAAM,mCAAmC,GAAI,OAAO,MAAM,EAAE,KAAG,MAAM,EAsB3E,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,+BAA+B,GAC1C,SAAS,MAAM,EACf,SAAS;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,KACrD,wBA2BF,CAAC"}